
X Extension ATIFGLEXTENSION
===========================

(Document revision: 1.0.0, 2003-01-16)

Index

    1. General Info
    2. XServer Configuration And Availability
    3. X-Extension Reference
    4. Principle Steps For Usage
    5. Compiling And Using The Library


1. General Info

Starting with driver version 2.6.5 the fglrx
linux driver is supporting the 

    >> X extension "ATIFGLEXTENSION" <<.

With this extension a programmer has among others
access to the global Gamma Correction Palette
and therefore can adjust screen apearance
in order to match the individual requirements
to contrast, brightness, saturation and other
parameters in a reasonable range. The current
implementation allows only write access.

The mentioned palette is best described as a table 
with 256 RGB-triples where each of this color 
components is represented by a 10 bit value.


2. XServer Configuration And Availability

Gamma correction can be enabled to apply for 
any screen content or for non-3D content only.
If the user wants to make use of antialiased lines, 
Gamma correction for 3D windwos must be disabled.


3. X-Extension Reference

- Extension name

"ATIFGLEXTENSION"

- X Protocoll Request Structure

typedef struct _FGLVidModeSetGammaRamp {
    CARD8   reqType;                /* Major Opcode - id code of the extension */
    CARD8   fireglReqType;          /* Minor Opcode X_* - Request Type Value */
    CARD16  length B16;             /* length of package in 4 byte units */
    /* X_FGLVidModeSetGammaRamp specific data */
    CARD32  screen B32;             /* handle of the screen to program */
    CARD32  controller B32;         /* display controller number */
    CARD16  RGamma[256];            /* red color value */
    CARD16  GGamma[256];            /* green color value */
    CARD16  BGamma[256];            /* blue color value */
} xFGLVidModeSetGammaRampReq;       /* size = 0xC08 */

The first 32 bits are part of the X Protocoll header
and must be set according to protocoll specs by the client.

The color values have to be in range 0x000 to 0x3FF to fit
the 10 bit range. The remaining upper 6 bits are not used.

- X Protocoll Reply Structure

typedef struct {
    BYTE    type;                   /* always X_Reply */
    BOOL    pad1;                   /* not used */
    CARD16  sequenceNumber B16;     /* reference to respective request */
    CARD32  length B32;             /* length of package in 4 byte units */
    /* X_Reply to X_FGLVidModeSetGammaRamp specific data */
    CARD32  pad2 B32;               /* offset 0x08 */
    CARD32  pad3 B32;               /* offset 0x0C */
    CARD32  pad4 B32;               /* offset 0x10 */
    CARD32  pad5 B32;               /* offset 0x14 */
    CARD32  pad6 B32;               /* offset 0x18 */
    CARD32  pad7 B32;               /* offset 0x1C */
} xFGLVidModeSetGammaRampReply;     /* size = 0x20 */

The first 64 bits are part of the X Protocoll header
and will be set according to protocoll specs by the server.

- X Protocoll Request Type Values

X_FGLVidModeSetGammaRamp = 0

Any other request type values are reserved
and will result in an error return value.
Later versions of this X extension might
implement further calls with different
functionality.


4. Principle Steps For Usage

Begin:
    Open display device

First step:
    Check whether the extension exists

Second step:
    Lock display

Third step:
    Get a pointer to a new request structure

Fourth step:
    Fill in the request structure

Fifth step:
    Carry out the extension function and wait for the reply

Sixth step:
    Unlock display

End:
    Close display device


5. Compiling And Using The Library

The sample code is provided in two parts, first a lib that
does simplify the usage of the interface a lot and second
a sample application that make use of that library.

The API of the library is designed to be rather similar
with the XF86 video mode extension, so coding for both of
these extensions at the same time will be easy. Please
note that the FIREGL23GAMMA extension provides only a
small subset of the XF86 video mode extension.

For reference on the librarys API please see the supplied
header file fgl_gamma.h and the other sources.

The supplied library needs an already compiled source tree
of XFree86 in order to compile. Extract the sources to:

    ~/xc/lib/fglrx_gamma

Change to this subdir and execute these commands:

    xmkmf -a ../.. lib/fglrx_gamma
    make

For usage copy the library to a lib directory of your choice
and then copy the related fgl_gamma.h header file to an include
or project directory of your choice.

Recommende locations are:

    /usr/X11R6/lib/libfglrx_gamma.*
    /usr/X11R6/include/X11/extensions/fglrx_gamma.h

If you have already installed the fglrx drivers then the
library and the header file got installed to the recommended 
ocations in the most recent version.

For reference on the sample application, please see the
README in the respective subdirectory.

### EOF ###
