ggiGetPixelFormat

Name

ggiGetPixelFormat — Get a structure describing the format of a pixelvalue from a visual

#include <ggi/ggi.h>

ggi_pixelformat *ggiGetPixelFormat(ggi_visual_t vis);

Description

This function obtains the default pixel format for the given visual.

Return value

Returns a pointer to the ggi_pixelformat structure.

Modifying the structure returned is not allowed. Do not attempt to free the pointer returned.

Structures

The ggi_pixelformat structure describes the format of a ggi_pixel. An application would use this if it wanted to directly output pixelvalues, rather than calling ggiMapColor or ggiPackColors to convert a ggi_color to a ggi_pixel value.

Other than the parameters of a ggi_graphtype that you can specifically request at mode setting, there is no other way to change the parameters of ggi_pixelformat. An application must not assume the presence of any particular pixelformat. If the application cannot handle a particular pixelformat, it should fall back on ggiMapColor, ggiPackColors or ggiCrossBlit.

/* Pixelformat for ggiGet/Put* buffers and pixellinearbuffers */
typedef struct {
        int             depth;          /* Number of significant bits */
        int             size;           /* Physical size in bits */

        /*
         * Simple and common things first :
         *
         * Usage of the mask/shift pairs:
         * If new_value is the _sizeof(ggi_pixel)*8bit_ value of the thing
         * you want to set, you do
         *
         * *pointer &= ~???_mask;               // Mask out old bits
         * *pointer |= (new_value>>shift) & ???_mask;
         *
         * The reason to use 32 bit and "downshifting" is alignment
         * and extensibility. You can easily adjust to other datasizes
         * with a simple addition ...
         */

        /* Simple colors:
         */
        ggi_pixel       red_mask;       /* Bitmask of red bits */
        int             red_shift;      /* Shift  for red bits */

        ggi_pixel       green_mask;     /* Bitmask of green bits */
        int             green_shift;    /* Shift  for green bits */

        ggi_pixel       blue_mask;      /* Bitmask of blue bits */
        int             blue_shift;     /* Shift  for blue bits */

        /* A few common attributes :
         */
        ggi_pixel       alpha_mask;     /* Bitmask of alphachannel bits */
        int             alpha_shift;    /* Shift  for alpha bits */

        ggi_pixel       clut_mask;      /* Bitmask of bits for the clut */
        int             clut_shift;     /* Shift  for bits for the clut*/

        ggi_pixel       fg_mask;        /* Bitmask of foreground color */
        int             fg_shift;       /* Shift  for foreground color */

        ggi_pixel       bg_mask;        /* Bitmask of background color */
        int             bg_shift;       /* Shift  for background color */

        ggi_pixel       texture_mask;   /* Bitmask of the texture (for
                                           textmodes - the actual character)
*/
        int             texture_shift;  /* Shift  for texture */

The above is used to describe a pixel simply. More detailed information, if required, can be obtained from the following fields. See ggi/ggi.h for a listing of bitmeanings.

        /*
         * Now if this doesn't suffice you might want to parse the following
         * to find out what each bit does:
         */

        uint32          bitmeaning[sizeof(ggi_pixel)*8];

        /* Shall we keep those ?
         */
        uint32          flags;          /* Pixelformat flags */

        uint32          stdformat;      /* Standard format identifier */
        /* This one has only one use for the usermode application:
         * To quickly check, if two buffers are identical. If both
         * stdformats are the same and _NOT_ 0 (which means "WEIRD"),
         * you may use things like memcpy between them which will have
         * the desired effect ...
         */

} ggi_pixelformat;

/* Pixelformat flags */
#define GGI_PF_REVERSE_ENDIAN   0x01
#define GGI_PF_HIGHBIT_RIGHT    0x02
#define GGI_PF_HAM              0x04
#define GGI_PF_EXTENDED         0x08

depth and size are same as the depth and access size information specified in the ggi_graphtype.

clut_mask is used in GT_PALETTE modes, indicating which bits correspond to an index to the CLUT (color look-up table).

fg_mask, bg_mask, and texture_mask are for text modes only, indicating the parts of the text-mode character.