XSGIvcQueryGammaMap(3)
XSGIvcStoreGammaColors8, XSGIvcStoreGammaColors16, XSGIvcQueryGammaColors, XSGIvcQueryScreenGammaMaps, XSGIvcQueryGammaMap, XSGIvcSetChannelGammaMap, XSGIvcQueryChannelGammaMap - Set and query gamma correction resources
As shipped in IRIX 6.5.7. Unchanged since IRIX 6.5.
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) 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. 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 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. 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. 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 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