XlibRGB: GDK-PixBuf Reference Manual

## XlibRGB XlibRGB — Rendering RGB buffers to X drawables. |

## Functions

void | xlib_rgb_init ()
void | xlib_rgb_init_with_depth ()
unsigned long | xlib_rgb_xpixel_from_rgb ()
void | xlib_rgb_gc_set_foreground ()
void | xlib_rgb_gc_set_background ()
void | xlib_draw_rgb_image ()
void | xlib_draw_rgb_image_dithalign ()
void | xlib_draw_rgb_32_image ()
void | xlib_draw_gray_image ()
XlibRgbCmap * | xlib_rgb_cmap_new ()
void | xlib_rgb_cmap_free ()
void | xlib_draw_indexed_image ()
Bool | xlib_rgb_ditherable ()
void | xlib_rgb_set_verbose ()
void | xlib_rgb_set_install ()
void | xlib_rgb_set_min_colors ()
Colormap | xlib_rgb_get_cmap ()
Visual * | xlib_rgb_get_visual ()
XVisualInfo * | xlib_rgb_get_visual_info ()
int | xlib_rgb_get_depth ()
Display * | xlib_rgb_get_display ()
Screen * | xlib_rgb_get_screen ()

## Types and Values

struct | XlibRgbCmap
enum | XlibRgbDither

## Includes

    #include <gdk-pixbuf/gdk-pixdata.h>

## Description

The XlibRGB set of functions is a port of the GdkRGB library to use plain Xlib and X drawables. You can use these functions to render RGB buffers into drawables very quickly with high-quality dithering.

## Functions

### xlib_rgb_init ()

    void
    xlib_rgb_init (Display *display,
                   Screen *screen);

Initializes the XlibRGB machinery with the default depth. If you use this function XlibRGB will automatically pick the best visual available on your display. This function or `xlib_rgb_init_with_depth()` must be called before using any of the other functions in XlibRGB.

#### Parameters

display | X Display to use. |
screen | Screen to use. |

### xlib_rgb_init_with_depth ()

    void
    xlib_rgb_init_with_depth (Display *display,
                              Screen *screen,
                              int prefDepth);

Initializes the XlibRGB machinery with a particular depth you specify, instead of automatically picking the best depth in the display. This function or `xlib_rgb_init()` must be called before using any of the other functions in XlibRGB.

#### Parameters

display | X display to use. |
screen | Screen to use. |
prefDepth | Visual depth to use for color substitution tables. This must be one of the supported visual depths in the specified `display` . |

### xlib_rgb_xpixel_from_rgb ()

    unsigned long
    xlib_rgb_xpixel_from_rgb (guint32 rgb);

Converts an RGB triplet into the closest color that XlibRGB visual can handle.

#### Parameters

rgb | 32-bit representation of an RGB value, specified as 0x00RRGGBB. |

#### Returns

X pixel value that corresponds to the closest color in the XlibRGB visual and colormap.

### xlib_rgb_gc_set_foreground ()

    void
    xlib_rgb_gc_set_foreground (GC gc,
                                guint32 rgb);

This is a convenience function to set the foreground of a GC from an RGB triplet. It calls `xlib_rgb_xpixel_from_rgb()` internally and uses the returned pixel value to set the GC's foreground.

#### Parameters

gc | A graphic context. |
rgb | 32-bit representation of an RGB value, specified as 0x00RRGGBB. |

### xlib_rgb_gc_set_background ()

    void
    xlib_rgb_gc_set_background (GC gc,
                                guint32 rgb);

This is a convenience function to set the background of a GC from an RGB triplet. It calls `xlib_rgb_xpixel_from_rgb()` internally and uses the returned pixel value to set the GC's background.

#### Parameters

gc | A graphic context. |
rgb | 32-bit representation of an RGB value, specified as 0x00RRGGBB. |

### xlib_draw_rgb_image ()

    void
    xlib_draw_rgb_image (Drawable drawable,
                         GC gc,
                         int x,
                         int y,
                         int width,
                         int height,
                         XlibRgbDither dith,
                         unsigned char *rgb_buf,
                         int rowstride);

Renders an RGB buffer to a drawable. Pixels are specified as RGB triplets with 8 bits per channel. An image will thus look like an RGBRGBRGBRGB sequence of 8-bit values. This function does not let you specify dither offsets; applications that need to render partial regions of a buffer to build the final image should use `xlib_draw_rgb_image_dithalign()` instead.

#### Parameters

drawable | Destination drawable. |
gc | A graphic context. |
x | Leftmost coordinate of the destination rectangle. |
y | Upper coordinate of the destination rectangle. |
width | Width of the destination rectangle, in pixels. |
height | Height of the destination rectangle, in pixels. |
dith | Dithering method to use. |
rgb_buf | Pointer to the pixel in the RGB buffer that corresponds to the upper-left corner of the rectangular region to render. |
rowstride | Offset between pixel rows in the RGB buffer, in bytes. |

### xlib_draw_rgb_image_dithalign ()

    void
    xlib_draw_rgb_image_dithalign (Drawable drawable,
                                   GC gc,
                                   int x,
                                   int y,
                                   int width,
                                   int height,
                                   XlibRgbDither dith,
                                   unsigned char *rgb_buf,
                                   int rowstride,
                                   int xdith,
                                   int ydith);

Renders an RGB buffer to a drawable. Pixels are specified as RGB triplets with 8 bits per channel. An image will thus look like an RGBRGBRGBRGB sequence of 8-bit values. This function lets you specify a pair of dither offsets. It should be used when you need to render regions of an RGB buffer separately to form the final image; the dither offsets let you align the dither mask appropriately.

#### Parameters

drawable | Destination drawable. |
gc | A graphic context. |
x | Leftmost coordinate of the destination rectangle. |
y | Upper coordinate of the destination rectangle. |
width | Width of the destination rectangle, in pixels. |
height | Height of the destination rectangle, in pixels. |
dith | Dithering method to use. |
rgb_buf | Pointer to the pixel in the RGB buffer that corresponds to the upper-left corner of the rectangular region to render. |
rowstride | Offset between pixel rows in the RGB buffer, in bytes. |
xdith | X offset for the dither mask. |
ydith | Y offset for the dither mask. |

### xlib_draw_rgb_32_image ()

    void
    xlib_draw_rgb_32_image (Drawable drawable,
                            GC gc,
                            int x,
                            int y,
                            int width,
                            int height,
                            XlibRgbDither dith,
                            unsigned char *buf,
                            int rowstride);

This function is analogous to `xlib_draw_rgb_image()`, but it lets you use 32-bit RGB buffers with pixels specified as 0xRRGGBB00. The least-significant 8 bits are actually discarded. This function can lead to faster results than `xlib_draw_rgb_image()` since the pixels are aligned on 32-bit boundaries.

#### Parameters

drawable | Destination drawable. |
gc | A graphic context. |
x | Leftmost coordinate of the destination rectangle. |
y | Upper coordinate of the destination rectangle. |
width | Width of the destination rectangle, in pixels. |
height | Height of the destination rectangle, in pixels. |
dith | Dithering method to use. |
buf | Pointer to the pixel in the RGB buffer that corresponds to the upper-left corner of the rectangular region to render. |
rowstride | Offset between pixel rows in the RGB buffer, in bytes. |

### xlib_draw_gray_image ()

    void
    xlib_draw_gray_image (Drawable drawable,
                          GC gc,
                          int x,
                          int y,
                          int width,
                          int height,
                          XlibRgbDither dith,
                          unsigned char *buf,
                          int rowstride);

Renders a grayscale buffer to a drawable. Pixels are specified as 8-bit intensity values. An image will thus look as a GGGGGG sequence of 8-bit values.

#### Parameters

drawable | Destination drawable. |
gc | A graphic context. |
x | Leftmost coordinate of the destination rectangle. |
y | Upper coordinate of the destination rectangle. |
width | Width of the destination rectangle, in pixels. |
height | Height of thd destination rectangle, in pixels. |
dith | Dithering method to use. |
buf | Pointer to the pixel in the grayscale buffer that corresponds to the upper-left corner of the rectangular region to render. |
rowstride | Offset between pixel rows in the grayscale buffer, in pixels. |

### xlib_rgb_cmap_new ()

    XlibRgbCmap *
    xlib_rgb_cmap_new (guint32 *colors,
                       int n_colors);

FIXME

#### Parameters

colors | FIXME |
n_colors | FIXME |

#### Returns

FIXME

### xlib_rgb_cmap_free ()

    void
    xlib_rgb_cmap_free (XlibRgbCmap *cmap);

Frees an XlibRGB colormap.

#### Parameters

cmap | An XlibRGB colormap. |

### xlib_draw_indexed_image ()

    void
    xlib_draw_indexed_image (Drawable drawable,
                             GC gc,
                             int x,
                             int y,
                             int width,
                             int height,
                             XlibRgbDither dith,
                             unsigned char *buf,
                             int rowstride,
                             XlibRgbCmap *cmap);

FIXME

#### Parameters

drawable | FIXME |
gc | FIXME |
x | FIXME |
y | FIXME |
width | FIXME |
height | FIXME |
dith | FIXME |
buf | FIXME |
rowstride | FIXME |
cmap | FIXME |

### xlib_rgb_ditherable ()

    Bool
    xlib_rgb_ditherable (void);

Queries whether XlibRGB supports dithering for its chosen visual.

#### Returns

TRUE if dithering can be performed for the visual that XlibRGB is using, FALSE otherwise.

### xlib_rgb_set_verbose ()

    void
    xlib_rgb_set_verbose (Bool verbose);

Enables/disables debug spew.

#### Parameters

verbose | True to be verbose |

### xlib_rgb_set_install ()

    void
    xlib_rgb_set_install (Bool install);

Sets whether we install an RGB colormap.

#### Parameters

install | True to install a colormap |

### xlib_rgb_set_min_colors ()

    void
    xlib_rgb_set_min_colors (int min_colors);

Sets the minimum number of colors in the color cube.

#### Parameters

min_colors | minimum colors to use |

### xlib_rgb_get_cmap ()

    Colormap
    xlib_rgb_get_cmap (void);

Queries the X colormap that XlibRGB is using.

#### Returns

An X colormap.

### xlib_rgb_get_visual ()

    Visual *
    xlib_rgb_get_visual (void);

Queries the visual that XlibRGB is using.

#### Returns

An X visual.

### xlib_rgb_get_visual_info ()

    XVisualInfo *
    xlib_rgb_get_visual_info (void);

Queries the visual info structure for the visual that XlibRGB is using.

#### Returns

An XVisualInfo structure.

### xlib_rgb_get_depth ()

    int
    xlib_rgb_get_depth (void);

Queries the depth of the visual that XlibRGB is using.

#### Returns

Bit depth.

### xlib_rgb_get_display ()

    Display *
    xlib_rgb_get_display (void);

Queries the X display that XlibRGB is using.

#### Returns

An X display.

### xlib_rgb_get_screen ()

    Screen *
    xlib_rgb_get_screen (void);

Queries the screen that XlibRGB is using.

#### Returns

An X screen.

## Types and Values

### struct XlibRgbCmap

    struct XlibRgbCmap {
      unsigned int colors[256];
      unsigned char lut[256]; /* for 8-bit modes */
    };

FIXME: Describe this.

#### Members

unsigned int `colors`[256]; | FIXME. |
unsigned char `lut`[256]; | FIXME. |

### enum XlibRgbDither

These values are used to specify which dithering method should be used. XLIB_RGB_DITHER_NONE will use no dithering and simply map the colors in an RGB buffer to the closest colors that the display can provide.

XLIB_RGB_DITHER_NORMAL will provide dithering

only on pseudocolor displays.

XLIB_RGB_DITHER_MAX will provide dithering on

pseudocolor and 16-bit truecolor or “high color” displays.

#### Members

XLIB_RGB_DITHER_NONE | Specifies no dithering. |
XLIB_RGB_DITHER_NORMAL | Specifies dithering only on pseudocolor displays. |
XLIB_RGB_DITHER_MAX | Specifies dithering on high color displays. |