 |
» |
|
|
|
This section provides instructions for setting and controlling
the environment variables that you can use to configure the PEXlib
client. To assure interoperability, your program should look for the
existence of environment variables, since these variables are implementation-dependent,
in order to use them as program parameters. If these do not exist,
then the program uses default values. Environment variables supported on HP workstations are summarized
in the following table. Additional information you'll need for implementing
them is provided either later in this chapter or in Chapter 6 “Writing HP PEXlib Programs ”, as appropriate. Table 3-3 Environment
Variable Summary Environment Variable Name | Range of Values | Description |
|---|
HPPEX_CLIENT_PROTOCOL | 〈default〉
[1]
, DHA, PEX, X | Desired rendering method. If method other
than default is specified, initialization fails if selected method
cannot be used. | HPPEX_DHA_ECHO_COLOR | #xxx
[2] | Default colors echoed for primitives
in a newly-created renderer. Note that echoing in HP PEX is done
using "exclusive-or" drawing mode. This means that the actual echo
color rendered will vary in different image locations, based upon
the frame buffer contents prior to rendering. | HPPEX_DHA_HIGHLIGHT_COLOR | #xxx
[3] | Colors highlighted for primitives. | HPPEX_DHA_COMPLIANCE_MODE | 〈any_value〉; e.g.,
True. | This variable enables complete PEXlib
compliance with the official standard specification. Because this
variable must be set in order to cause complete compliance, HP PEXlib
runs in the highest-performance mode by default. If your application
cannot tolerate any differences from the standard, then set this
variable. It is recommended this variable be set during development
of an application to enable more robust error-checking. Because
users must explicitly set HPPEX_DHA_COMPLIANCE_MODE,
HP PEXlib's default behavior will exhibit minor differences from
the standard. | HPPEX_DHA_AUTO_COLOR_APPROX | 〈any_value〉;
e.g., True. | When this variable is not
set, HP PEX provides standard behavior with respect to the setting
of the color approximation table. When this variable is set to any
value, HP PEX enables some clients to run successfully that would
otherwise abort, attempting to set an unsupported color approximation
entry (which is not standard PEX behavior). | SB_X_SHARED_CMAP | 〈any_value〉;
e.g., True. | If you are using a low-end graphics device
with only one hardware colormap, you can avoid color flashing through
the use of this variable, setting it to any value. Use of SB_X_SHARED_CMAP and achieving
generally satisfactory behavior requires some explanation; please
see additional information in “Using SB_X_SHARED_CMAP ”. | HP_DISABLE_COLOR_RECOVERY | 〈any_value〉;
e.g., True. | When this variable is set to any value
before PEXBeginRendering
or other similar entrypoint that binds the renderer to the window,
the color recovery feature is disabled. For more on the use of this
environment variable, see “Environment Variable —
Color Recovery ”. | HP_ENABLE_TRANSPARENT_MODE | 〈any_value〉;
e.g., True | When this variable is set to any value,
before starting the X11 server, the overlay planes become transparent.
For more on the use of overlay planes and this environment variable,
see “2: Determine Use of Transparent Overlay
Planes ”. | HP_COUNT_
TRANSPARENT_IN_ OVERLAY_VISUAL | 〈any_value〉;
e.g., True | Determines whether or not you want to
count the "transparent color" as a real color in the overlay visual.
(Formerly named CRX24_COUNT_TRANSPARENT_IN_
OVERLAY). | HPPEX_TXTR_SHMEM_THRESHOLD | | If an application wants to adjust the
threshold to a lower limit, this variable can be exported. This
variable will set the decimal number of bytes for a shared memory
segment. The current threshold for texel maps is greater than or
equal to a 1024 x 1024 x 3 byte (3MB) size. The system will attempt
to allocate a shared memory segment. |
How To Set Environment Variables | |
There are two ways to set environment variables. The choice
depends on whether you are using HP CDE or if you are simply using
the X environment. Both methods are illustrated using the HP_ENABLE_TRANSPARENT_MODE
environment variable: Setting Environment Variables
In HP CDE If you are using HP CDE (Common Desktop Environment) add the
following line to your Xconfig
file: Dtlogin*environment:HP_ENABLE_TRANSPARENT_MODE=TRUE |
The Xconfig
file may contain commented out entries for some of the more popular
resources, including "environment".
You need to find the line containing "environment",
add the appropriate value, and uncomment the line. To eliminate
the overlay plane, remove the line. Setting Environment Variables In X Windows If you are using x11start,
make sure you have the environment variable HP_ENABLE_TRANSPARENT_MODE
set before you execute x11start: export HP_ENABLE_TRANSPARENT_MODE=TRUE |
The best way to do this is to include it in your $HOME/.profile. To eliminate
the overlay plane, this environment variable is unset by typing: unset HP_ENABLE_TRANSPARENT_MODE |
...and restarting the X11 server.
Using Environment Variables | |
Environment Variable — To Specify Color Color resources are set using color names either from the
X11 color database rgb.txt,
or using the syntax #RedGreenBlue
where Red, Green,
and Blue are hexadecimal numbers containing
1, 2, 3, or 4 digits (that is, #rgb,
#rrggbb,
#rrrgggbbb,
and #rrrrggggbbbb
are all legal syntaxes). These hexadecimal numbers indicate the
amount used of that primary color. There must be the same number
of digits for each of the primary colors. For example, color names from rgb.txt
or a color specified by one of these can take the following form
(where r, g,
and b are hexadecimal digits): #rrrgggbbb
12
bits per color |
#rrrrggggbbbb
16
bits per color |
To set an environment variable for color, you may use this
syntax: export
HPPEX_DHA_ECHO_COLOR=red export HPPEX_DHA_ECHO_COLOR="#ffff00000000"
Colors are set, using the syntax shown above, for these HP
environment variables: HPPEX_DHA_ECHO_COLOR
HPPEX_DHA_HIGHLIGHT_COLOR |
The default colors are echoed for primitives in a newly-created
Renderer. Note that echoing in HP PEX is done using "exclusive-or"
drawing mode. This means that the actual echo color rendered will
vary in different image locations based upon the frame buffer contents
prior to rendering. More information about application resources, including color,
is found in the book Using the X Window System. Environment Variable — PEX Protocol MethodWhen using the PEX Protocol Method of connecting to the server,
(that is, you have set HPPEX_CLIENT_PROTOCOL
to PEX), you
must reset the following environment variables, if you wish to use
them, before the X server is started on the
PEX server's system for the variables to have an effect: HPPEX_DHA_ECHO_COLOR
HPPEX_DHA_HIGHLIGHT_COLOR
HPPEX_DHA_COMPLIANCE_MODE
HPPEX_DHA_AUTO_COLOR_APPROX |
Setting these variables before starting the client process
will not affect the PEX server which, ultimately, does the final
rendering. Environment Variables — Compliance Mode The environment variable HPPEX_DHA_COMPLIANCE_MODE
allows users to specify whether HP PEXlib strictly adheres to the
standard, or to maximize HP PEX's performance, allowing some minor
behavioral differences. In most PEXlib applications, these differences
should be acceptable and preferable for the performance edge. For
this reason this is the default behavior; that is, the variable
is not set. If your application cannot tolerate any differences from the
standard, then set this variable. It is also recommended this variable
be set during development of an application to enable more robust
error checking. Because users must explicitly set HPPEX_DHA_COMPLIANCE_MODE,
this default behavior will exhibit minor differences from the standard. Here are the differences from the standard when HPPEX_DHA_COMPLIANCE_MODE
is off: Specular Reflections
— A directional eyepoint is used in lighting calculations;
this is manifested as subtle changes in specular reflections. Disabled Clamping —
Clamping of ambient, diffuse, and specular reflection attribute
values is disabled. Error Checking — Comprehensive
parameter error checking is not performed. The burden of transmitting
good data to PEXlib procedures is placed upon the application. Higher Performance —
The fastest transformation and rasterization paths are enabled to
give applications a significant performance boost.
Because invalid data can cause programs to fail, Hewlett-Packard
suggests the compliance mode variable be set during development
of the application, and unset once the application is defect-free.
The precise performance differences with the mode set and unset
vary with the application. The application documentation should
specify whether or not this variable should be set. Using HPPEX_DHA_AUTO_COLOR_APPROX When the variable HPPEX_DHA_AUTO_COLOR_APPROX
is not set, HP PEX checks the values in a color
approximation table entry and reports an error if any of the values
do not match what is supported on the particular device and visual. If the variable is set to any value, HP PEX recognizes unsupported
values as the color approximation entry values are set. But rather
than reporting an error, it creates and initializes a new X color
map with a supported content for any window on which the invalid
color approximation entry is used at the time it is installed. While
this is not standard PEX behavior, the advantage is that it allows
some clients to run that would otherwise fail. On graphics devices with only one hardware colormap, PEX applications
may experience "color flashing." Color flashing is the condition
where colors displayed on the workstation screen change as the focus
moves from X window to X window and where the PEX image looks correct
only when the focus is in its window. This is common on low-end graphics devices because most PEX
applications are demanding in their color usage, more demanding
than many other X clients and window managers. Therefore, the PEX
default color sampling requires a different colormap setup than
many X clients and window managers. When the graphics device only
supports one hardware colormap, both colormaps cannot be installed
at the same time, and the switch from one colormap to another in
hardware causes color flashing. HP offers a method for avoiding color flashing on low-end
graphics devices through the use of the environment variable SB_X_SHARED_CMAP. The use
of this environment variable is explained in further detail below.
However, you need to be aware that this may result in anomalous
color behavior with some color-demanding X clients and window managers
such as HP CDE. (An example of aberrant color behavior would be
the minute hand on the clock in the HP CDE front panel leaving behind
a different color as it moves around the face of the clock.) If you are using a low-end graphics device with only one hardware
colormap, you can avoid color flashing through the use of the SB_X_SHARED_CMAP environment
variable. This is the best choice if you do not use color-demanding
X clients and window managers such as HP CDE in "High Color" mode
(the default HP CDE color mode). If you must avoid aberrant color
behavior by color-demanding X clients, then this method is not available
to you. In general, if you attempt to share X colormaps among color-demanding
X and PEX applications on a low-end graphics device, you may experience
unexpected color behavior. The setting of the SB_X_SHARED_CMAP
environment variable determines the supported PEXColorSpace color approximation
entry on the display. This environment variable has effect only
on older simple HP displays that only support depth 8 visuals and
exerts its effect at the time that the X/PEX server is started.
(Changing the value after the server is running has no effect, except
when X protocol mode is being used with a non-HP server. In this
case, the local value of the variable at the time the PEX application
is started controls the color approximation support.) SB_X_SHARED_CMAP
is especially important if you have PEX applications that need to
share a colormap (perhaps the default colormap) with other X clients.
In such a case, it is common for the X clients and window managers
to be using pixel values in the low end of the colormap, for X rendering
and for borders and backgrounds. On all of the single-visual devices,
HP PEX supports a colormap in which the lowest forty cells are available
for X clients, and the upper 216 cells are set up in an RGB color
space sampling that HP PEX supports via PEXColorSpace approximation.
This colormap configuration is often called a "6|6|6"
colormap, because the color sampling includes six levels each of
red, green, and blue. The 6|6|6 default colormap setup and PEX
color approximation support are enabled by setting SB_X_SHARED_CMAP to any value
before the X/PEX server is started. If SB_X_SHARED_CMAP
is not set, HP PEX supports a color sampling using 8 values of red,
8 of green, and 4 of blue. This colormap configuration is called
"8|8|4." (It is also sometimes called "3:3:2",
for the number of planes allocated to each of red, green, and blue.
Note that "|" is used to delimit color levels and ":" is
used to delimit frame buffer planes.) Since 8|8|4
mode consumes all 256 cells in the colormap, a PEX application must
use a colormap other than the default. Regardless of which protocol method of connecting to the server
is used, you must reset the environment variable, SB_X_SHARED_CMAP, if you
wish to use it, before the X server is started
on the PEX server's system for the variable to have an effect. On devices with only one hardware colormap, both the 6|6|6
colormap being used by the other clients, and the 8|8|4
colormap being used by PEX, cannot be installed at the same time.
This results in "color flashing", since the PEX image will not look
correct except when the 8|8|4 colormap is installed. | | | |  | NOTE: If your PEX application does not require the higher
8|8|4 color resolution, set your SB_X_SHARED_CMAP environment
variable to "True" on these lower-end graphics devices. Be aware
that this may result in aberrant color behavior on the part of other
color-demanding X applications as discussed above. However, setting
the environment variable will allow many PEX applications to share
a colormap with other clients, avoiding the "color flashing" problem. | | | | |
The CRX Device And Color Support The CRX device (only) exhibits one exception to standard X/PEX
color support. For best performance, it requires a color sampling
(either 6|6|6 or 8|8|4) in the
colormap that contains the same number and values of cells as the
other single-visual devices, but the cells are not in the "canonical"
order described by X standard colormap properties or PEX color approximation
entries. HP provides a program, xhpcmap,
to transform a canonical color sampling into the required "shuffled"
setup. If your PEX applications all use this utility or equivalent
code, you can set SB_X_SHARED_CMAP
to "True" as described above, and obtain the best performance possible
on the CRX. If, however, you have applications that do not incorporate
code to set up the "shuffled" colormap, or there are other reasons
why the special colormap is unacceptable, you can set SB_X_SHARED_CMAP to the special
value XA_RGB_DEFAULT
before starting the X/PEX server. HP PEX will render correctly using
a canonical 6|6|6 colormap, but rendering performance
on CRX may be noticeably impacted. The only mechanism to cause rendering
to a canonical 8|8|4 colormap on CRX is to set
HPPEX_CLIENT_PROTOCOL
to "X" though,
again, performance may be affected. Environment Variable —
Color Recovery In order to provide higher-quality shaded images on low-cost
3D graphics systems like the Model 712, as well as the HCRX-8 devices,
you can take advantage of a new feature called color recovery.
Color recovery provides better pictures on low-cost workstations
than are possible using only dithering by attempting to eliminate
the apparent graininess caused by dithering. Use of the color recovery feature attaches a different colormap
to the X window than the application originally attaches. The colormap
substitution occurs on the first PEXBeginRendering
or other similar entrypoint that binds the renderer to the window.
However, since it only occurs in TrueColor
visuals, color flashing due to this change should not be objectionable.
Applications that attempt to free the colormap they created will
succeed; it is recommended that they not assume they can free whatever
colormap is currently attached to the window, since the substitution
may have occurred and they will get a permissions error. Color recovery requires a different dither cell size when
rendering shaded polygons and a digital filter is used when displaying
the contents of the frame buffer to the screen. For this reason,
color recovery can occasionally produce undesirable artifacts in
the image. Some applications that read or write PEX images as raster
images may be affected by the different dither cell. To disable color recovery, you'll need to set and export the
environment variable HP_DISABLE_COLOR_RECOVERY
in the environment in which the X/PEX server is started before running
your application. This disables the colormap substitution and color
recovery. However, if this environment variable is not set in the
server's environment, but is set in the DHA client's environment,
color recovery is disabled for the client only. The color recovery colormap is a read-only colormap. Attempts
to change it are ignored and errors are not reported. Environment Variable — Turning Off the TrueColor
Visual TrueColor
visuals are supported with 9.05 release and later releases of HP-UX.
Note that applications created prior to the 9.03 release of HP-UX
may exercise new paths through their source when using this visual.
To avoid compatibility problems, an environment variable has been
included in X Windows for the HP-UX 9.03 and 9.05 release
only. The name of this environment variable is: HP_SUPPRESS_TRUECOLOR_VISUAL |
| | | | | NOTE: The HP_SUPPRESS_TRUECOLOR_VISUAL
environment variable is supported on HP-UX 9.03 and 9.05 only. It
will not be supported in future releases of HP-UX. | | | | |
The existence (not the value) of the HP_SUPPRESS_TRUECOLOR_VISUAL
environment variable before starting the X11 server disables the
TrueColor visual. If you set this environment variable after starting
X11 server, it will be ignored. To set the HP_SUPPRESS_TRUECOLOR_VISUAL
environment variable before the X11 server is started, use one of
the methods given below. If you are using x11start,
make sure you have the environment variable HP_SUPPRESS_TRUECOLOR_VISUAL
set before you execute x11start: export HP_SUPPRESS_TRUECOLOR_VISUAL=TRUE |
The best way to do this is to include it in your $HOME/.profile. To unset the environment variable, type: unset HP_SUPPRESS_TRUECOLOR_VISUAL |
and restart the X11 server. If you are using HP CDE (Common Desktop Environment) add the
following line to your Xconfig
file: Dtlogin*environment:HP_SUPPRESS_TRUECOLOR_VISUAL=TRUE |
The Xconfig
file may contain commented out entries for some of the more popular
resources, including "environment." Simply find the line containing
"environment," add the appropriate value, and uncomment the line. To unset the environment variable, remove this line: Dtlogin*environment:HP_SUPPRESS_TRUECOLOR_VISUAL=TRUE |
from your Xconfig
file and restart the X11 server. |
Printable version
