SunView.\" @(#)reservecolors.1 1.9 91/01/31
.TH reservecolors 1 "22 January 1993"
.SH NAME
reservecolors \- reserve colors in the X11/NeWS default colormap
.IX reservecolors#(1) "" "\fLreservecolors\fP(1)"
.SH SYNOPSIS
.B reservecolors
[
.B \-display
.I dpy
]
[
.B \-svmono
]
[
.B \-invramp
]
[
.B \-nokeep
]
[
.B \-discard
]
.SH DESCRIPTION
.LP
\fBreservecolors\fP reserves colors in the default colormap of the default screen
at specified pixel locations. It sets aside "placeholder" colors
corresponding to colors in some other colormap with the intent of reducing
colormap flashing. The colors and locations specified should be the same
as those allocated in this other colormap. The presence of these reserved
colors causes other color allocations to avoid these positions and to
therefore not flash against the colors in the other colormap.
.sp
Its main purpose is to reduce colormap flashing with SunView programs
running under the \fISunView Binary Compatibility\fP mode of X11/NeWS (not supported in Solaris 2.1 for x86).
.sp
The pixel locations and color values to allocate are taken from standard
input. Each line of standard input contains the specification for one
pixel. An input line has the following format:
.sp
<pixel> <color spec>
.sp
<pixel> is an integer value between 0 and 255. <color spec> is an X11 color
specification, which is either a color name string or a hexadecimal RGB
specification. The two fields are separated with whitespace. The list of valid
color name strings and their corresponding values can be found in
\f3$OPENWINHOME/lib/rgb.txt\f1. Refer to \f3XParseColor\f1 in the \f2Xlib Reference
Manual\f1 for details on X11 hexadecimal RGB specifications.
.sp
The pixels are allocated as read-write (non-sharable) colormap cells, so while
the pixels are reserved they are unavailable to be shared by X11/NeWS
applications.
.sp
To deallocate reserved pixels, run \fBreservecolors\fP with the \fB\-discard\fP
option. The options \f3-svmono\fP and \f3-nokeep\fP are ignored when
\f3-discard\fP is used.
.sp
When the server has been started in the default configuration, there are
already two pre-existing read-only colors at pixel locations 0 and 1 (white
and black); these are \fIserver owned\fP locations. \fBreservecolors\fP will not
be able to allocate colors at server owned locations. Attempts to do so will
generate an error. If colormap compaction is enabled (see
.BR cmap_compact (1),
the server owned locations will be at 254 and 255.
.sp
A common use of this utility is to reserve the colors Black and White
in the same pixel locations used by SunView monochrome programs (e.g.
.BR cmdtool ).
Because of this, a simplified way is provided to specify this
situation. If \f3-svmono\fP is specified, the colors and pixels used
by SunView monochrome programs are reserved. Standard input is ignored
in this case.
.sp
.br
.ne 5
Similarly, there is another convenience option called \fI-invramp\fP which can
be used to allocate an inverse grayscale ramp in pixel locations 2 to 31.
This ramp has gray values which proceed from #efefef down to #000000 and
is compatible with the colors used by FrameMaker 2.0. Again, standard input
is ignored whenever a convenience option like this is used.
.sp
Both \fI-svmono\fP and \fI-invramp\fP may be used together on the same
command line.
.sp
In order to effectively use the feature which reads the pixel locations
and color values from standard input, you must know the specific pixel
locations and color values used by the program (or programs) with which
you want to reduce colormap flashing. This information may not always
be documented and may be difficult to figure out, so this particular
feature is typically only useful to application developers.
.sp
An invocation of \fBreservecolors\fP is typically added to \fL~/.xinitrc\fP.
It should be placed before the invocation of any program that allocates
colors (such as the window manager). To reduce colormap flashing on multiple screens,
\fBreservecolors\fP should be run once for each screen, and should be placed before the
invocation for each screen of any program that allocates colors.
.sp
If \f3\-nokeep\fP is specified, rather than permanently reserving colors
in the default colormap, \fBreservecolors\fP simply loads the specified
values into the hardware colormap. Note: these pixels may lie in unallocated
areas of the default colormap and their contents may be displaced
the next time a colormap is installed. No color cells are actually allocated
so it does not matter if the default colormap is not dynamic.
.sp
This utility can only be used when the default colormap class (\fIvisual\fP)
for the screen is dynamic. That is to say, this utility may not be run
when \fBxnews\fP is started with the \fIstaticvis\fP device modifier.
An error message will be printed if this should happen and no colors
will be reserved.
.sp
This utility may not always reduce colormap flashing, and in
some environments, might actually increase it. You should
use it only if it is effective in your environment. For example,
if you reserve too many colors the default colormap might fill up,
causing X11 programs which would ordinarily use the default colormap to start
overflowing into private colormaps. Colormap flashing usually increases when this happens.
Thus, this utility should be used judiciously.
.sp
This utility does not provide a general solution to the problem of
colormap flashing. It only suffices to reduce colormap flashing
for a few selected applications.
.SH OPTIONS
.TP 2
.B \-display
The X11 display to which to connect.
.br
.ne 6
.TP 2
.B \-svmono
Reserves colors compatible with SunView monochrome programs running under
\fISunView Binary Compatibility\fP mode of X11/NeWS (not supported in Solaris 2.1 for x86). These colors currently are
"White" at pixel 254 and "Black" at pixel 255.
.TP 2
.B \-invramp
Reserves colors compatible with the SunView program FrameMaker 2.0.
.TP 2
.B \-nokeep
Do not allocate the specified colors in the default colormap. Load the values
only into the hardware colormap. These colors may be displaced by subsequent
colormap \%installations.
.TP 2
.B \-discard
Discard the allocated colors reserved by all previous invocations of \fBreservecolors\fP
for the default screen of the specified display.
.SH EXAMPLES
For example, to set aside the two pixel locations that SunView monochrome
programs use, add the following command to \fL~/.xinitrc\fP (prior to invoking
\fBolwm\fP):
.sp
.nf
$OPENWINHOME/bin/reservecolors -svmono
.fi
.sp
As another example, suppose we have a hypothetical SunView color
program which uses the following pixel locations and colors:
.sp
.nf
Red at pixel 2
Green at pixel 3
Blue at pixel 4
Yellow at pixel 5
.fi
.sp
To avoid colormap flashing between applications which use the default colormap
and this SunView application, add the following command to \fL~/.xinitrc\fP
(prior to invoking \fBolwm\fP):
.sp
.nf
$OPENWINHOME/bin/reservecolors <<EOF
2 Red
3 Green
4 Blue
5 Yellow
EOF
.fi
.sp
.br
.ne 6
Instead of using color names, hexadecimal RGB specifications could also
have been used:
.sp
.nf
$OPENWINHOME/bin/reservecolors <<EOF
2 #ff0000
3 #00ff00
4 #0000ff
5 #ffff00
EOF
.fi
.sp
Refer to \fLXParseColor\fP in the
.I Xlib Reference Manual"
for more information about
hexadecimal RGB specifications.
.sp
.SH FILES
.TP
\fB~/.xinitrc\fP
.SH "SEE ALSO"
.BR cmap_compact (1),
.BR olwm (1),
.BR openwin (1),
.BR xnews (1)
.LP
.TZ OWPG
.LP
.I Xlib\ Reference\ Manual
.SH NOTES
On Solaris 2.1 for x86, X11/NeWS does not support SunView compatibility mode.