XSGIvcStoreGammaColors(3)XSGIvcStoreGammaColors(3)
NAME
XSGIvcStoreGammaColors8, XSGIvcStoreGammaColors16,
XSGIvcQueryGammaColors, XSGIvcQueryScreenGammaMaps,
XSGIvcQueryGammaMap, XSGIvcSetChannelGammaMap,
XSGIvcQueryChannelGammaMap - Set and query gamma correction
resources
SYNOPSIS
#include <X11/extensions/XSGIvc.h>
Status XSGIvcQueryScreenGammaMaps(Display *display,
int screen,
int *gammaMapsReturn)
Status XSGIvcQueryGammaMap(Display *display,
int screen,
int gammaMap,
int *gammaSizeReturn,
int *gammaPrecisionReturn,
int *gammaMapAttributes)
void XSGIvcStoreGammaColors8(Display *display,
int screen,
int gammaMap,
int itemCount,
long loadTables
const unsigned char *gammaValue)
void XSGIvcStoreGammaColors16(Display *display,
int screen,
int gammaMap,
int itemCount,
long loadTables
const unsigned short *gammaValue)
Status XSGIvcQueryGammaColors(Display *display,
int screen,
int gammaMap,
int requestedColor,
int *itemCountReturn,
unsigned short **gammaValueReturn)
void XSGIvcSetChannelGammaMap(Display *display,
int screen,
int channel,
int gammaMap)
Status XSGIvcQueryChannelGammaMap(Display *display,
int screen,
int channel,
int *gammaMapReturn)
Page 1 (printed 7/20/06)
XSGIvcStoreGammaColors(3)XSGIvcStoreGammaColors(3)
PARAMETERS
gammaMapsReturn
Returns the number of gamma maps available on
the server. Pass the address of a variable to
receive this value.
display Specifies the connection to the X server.
screen Specifies the screen of the X server.
channel Specifies the channel number.
gammaMap Specifies which of the gamma maps within the
server should be affected. Gamma map IDs are
not X resources, but are numbered implicitly,
starting with 0.
itemCount Specifies the number of elements in the gamma
table to be loaded.
itemCountReturn
Specifies a pointer to an integer that is to
contain the number of elements in the gamma
table.
loadTables The gamma tables which should be loaded with
this command. To economize traffic, you should
load all tables simultaneously if you intend to
set each color component to the same values.
You may use a bitwise OR of the constants
XSGIVC_MComponentRed, XSGIVC_MComponentGreen,
XSGIVC_MComponentBlue, or
XSGIVC_MComponentAlpha.
gammaValue Specifies a pointer to an array containing gamma
elements. The number of items of each array
must be that specified in itemCount.
gammaReturn Specifies a pointer to a location that is to
contain a pointer to an array containing the
returned gamma map.
Page 2 (printed 7/20/06)
XSGIvcStoreGammaColors(3)XSGIvcStoreGammaColors(3)
gammaSizeReturn
Specifies a location which is to receive the
size of the gamma table (i.e., the number of
entries in the gamma table).
gammaPrecisionReturn
Specifies a location which is to receive the
precision in bits of the gamma table. For
example, if each entry in the gamma table is 10
bits long, the call returns 10.
gammaMapAttributes
A bitmask describing attributes of the gamma
map. The bitmask may contain one or more of the
following attributes: XSGIVC_GMAlphaPresent, or
XSGIVC_GMHardwareApproximation. See the
discussion below for a more thorough treatment
of attributes
requestedColor
For queries, specifies which color component's
information should be returned. Use the
constants XSGIVC_COMPONENT_RED,
XSGIVC_COMPONENT_GREEN, XSGIVC_COMPONENT_BLUE,
or XSGIVC_COMPONENT_ALPHA. The server may
ignore the alpha component if the gamma map does
not have an alpha component; see
XSGIvcQueryGammaMap.
DESCRIPTION
Gamma Correction and Server Configuration
Cathode ray tubes (CRTs) have the unfortunate characteristic
that their display is non-linear: the intensity of light
displayed at a pixel is not strictly proportional to the
voltage supplied to the CRT at that pixel. Gamma correction
is used to compensate for that non-linearity so the monitor
does produce the proper intensity.
A server may contain one or more gamma maps, each of which
may perform an independent correction by serving as a look-
up table. A gamma map has two distinguishing features: the
number of entries in the table (i.e., each gamma color) and
the width of each entry. These correspond to the input and
output values, respectively, as each pixel is processed
through the look-up table.
Depending on server configuration, a channel may use one of
Page 3 (printed 7/20/06)
XSGIvcStoreGammaColors(3)XSGIvcStoreGammaColors(3)
one or more gamma maps. Servers may assign a permanent
gamma map to a channel, restrict channels to use one of a
subset of all maps, permit a channel to use one of all
shared maps, or some combination thereof, depending on
hardware configuration. If two channels employ the same
gamma map, changing the colors in that gamma map will affect
both channels.
Functions
XSGIvcQueryScreenGammaMaps returns the number of separate
gamma maps supported. For each gamma map supported, the
system returns the number of entries supported. Each color
component in a gamma map must support the same number of
entries, different gamma maps may support different numbers
of entries. Systems with no writable gamma map should return
a count of zero (0). XSGIvcQueryGammaMap returns information
regarding a specified gamma map's configuration.
The XSGIvcStoreGammaColors8 and XSGIvcStoreGammaColors16
functions change the gamma map entries for the specified map
to the specified colors, the former function loading 8-bit
entries and the latter loading 16-bit entries. To load a
gamma color, you pass a single array of values via
gammaValue and specify into which color components that
array will be loaded. The doRed, doGreen, doBlueand doAlpha
arguments indicate which components should actually be
changed. If you select more than one component, each
component will be loaded with the same values; you may
select any one or a combination of the colors to load.
N.B.: The hardware of some servers may require the server to
load all components simultaneously in an encoded (packed)
manner, so choosing a single color component may require the
server to query the gamma table to encode the component
before writing it; thus, the most efficient use of this
function may be to store all color components
simultaneously.
All tables loaded via a single call must have the same
number of entries, specified via the parameter itemCount.
Note that the count of the number of entries you load in a
table must exactly equal the length of the table (returned
via the parameter gammaSizeReturn in the function
XSGIvcQueryGammaMap).
XSGIvcQueryGammaColors() returns the gamma values for the
specified gamma map. The number of items in the requested
color component is returned in itemCountReturn. Use XFree()
to free the memory allocated in gammaValueReturn.
Page 4 (printed 7/20/06)
XSGIvcStoreGammaColors(3)XSGIvcStoreGammaColors(3)XSGIvcSetChannelGammaMap() selects the specified channel to
use the specified gamma map. On server startup, each
channel uses the lowest-number gamma map available to it.
XSGIvcQueryChannelGammaMap() returns the gamma map ID
associated with the specified channel.
The function XSGIvcStoreGammaColors8 is provided as an
economy to the function XSGIvcStoreGammaColors16 because it
minimizes traffic between the client and X server. You
should use the operation that best suits your need: for
rapid animations, you may prefer the 8-bit function; for
greater accuracy, the 16-bit function.
Server's Operations on Colors During Store
If you store a gamma map's colors using a function whose
width is different than the width of the gamma map, the
server will alter the values when loading the gamma
hardware. This alteration occurs for each color value you
specify.
If you use a function whose width is larger than that of the
table, the server will truncate, using only the most-
signficant bits (MSBs) of your values; for example, if you
use the XSGIvcStoreGammaColors8 function to store values
into a table that contains only five bits, the server will
use only the upper five MSBs of your color values,
discarding the lower three bits.
If you use a function whose width is narrower than the
table, the server will use your stored values for the most-
significants bits (MSBs), and store into the unsupplied
least-signficant bits (LSBs) a copy of the most significant
bits; for example, if you use the XSGIvcStoreGammaColors8
function to store values into a table that contains 12 bits,
the server will store your values into the eight MSBs,
copying the upper four bits of each of your values into each
entry's LSBs.
Server's Operations on Colors During Query
The XSGIvcQueryGammaColors function implicitly returns 16-
bit quantities, irrespective of the precision of the
underlying hardware. If the gamma map's precision is less
than 16 bits, the server will return the significant bits of
the precision in the uppermost bits of the returned 16-bit
quantity; the least significant bits of the returned
quantity will contain replicated copies of the gamma map's
MSBs.
Page 5 (printed 7/20/06)
XSGIvcStoreGammaColors(3)XSGIvcStoreGammaColors(3)
This operation is similar and complementary to the actions
taken during store operations. For example, if the hardware
gamma map has 11 significant bits, the 16-bit value returned
to the client will contain the hardware's value in bits the
upper 11 bits. The most significant five bits of the
hardware's value will be replicated in the lower four bits
of the returned value.
In general, the significant bits of the returned value may
be determined via the following C-language statement (given
precision as the width of the gamma entry and
gammaValueReturn as the returned value):
unsigned short sigBits;
...
sigBits = (gammaValueReturn >> (16 - precision));
You can use the function XSGIvcStoreGammaColors16 as a
complementary store operation; that function expects a value
with the significant bits similarly shifted into the MSBs.
Gamma Map Attributes
Some gamma maps may have certain attributes which modify
their operation. The attributes of the gamma map may be
retrieved by calling XSGIvcQueryGammaMap. The attributes
are:
XSGIVC_GMAlphaPresent
The gamma map has an alpha component in addition to the
red, green, and blue components.
XSGIVC_GMHardwareApproximation
The server hardware may use private techniques to
approximate the stated size and precision of the gamma
map, substituting a less thorough representation. In
most cases when you load a gamma-shaped curve, the
visual result will not be different from that of a
gamma map which has not undergone hardware
approximation. Queries of the value of the colors of
this gamma map will return the values as previously
stored, not of the internal approximation. The
techniques used to approximate the gamma map are at the
discretion of the server.
XSGIVC_GMWriteLock
The gamma map cannot be modified programmatically. The
server hardware may have a fixed gamma map or the
server does not implement alteration of this map.
XSGIVC_GMReadLock
The gamma map cannot be queried programmatically. The
Page 6 (printed 7/20/06)
XSGIvcStoreGammaColors(3)XSGIvcStoreGammaColors(3)
server hardware may not permit readback or the server
does not implement readback of this map.
EVENTS
When this control is altered, the server generates a
GammaMapNotify event.
RETURNED VALUE
XSGIvcQueryGammaColors, XSGIvcQueryChannelGammaMap,
XSGIvcQueryGammaMap, and XSGIvcQueryScreenGammaMaps return
TRUE if successful, FALSE upon failure.
Parameter errors are reported via BadValue or BadMatch.
DIAGNOSTICS
In the XSGIvcStoreGammaColors8() and
XSGIvcStoreGammaColors16() functions, a Value error is
generated if a specified pixel is not a valid index into the
gamma map. If more than one pixel is in error, it is
arbitrary as to which pixel is reported. A Colormap error
is generated if the map id is not valid.
In the XSGIvcQueryGammaColors() function, a Colormap error
is generated if the gamma map id is invalid. A Value error
is generated if a pixel is invalid. If more than one pixel
is in error, it is arbitrary as to which pixel is reported.
SEE ALSO
XSGIvc
Page 7 (printed 7/20/06)
