XlibRGB
3
GDK-PIXBUF Library

# XlibRGB

Rendering RGB buffers to X drawables.

## Synopsis

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

                        XlibRgbCmap;
    enum                XlibRgbDither;
    void                xlib_rgb_init                       (Display *display,
                                                             Screen *screen);
    void                xlib_rgb_init_with_depth            (Display *display,
                                                             Screen *screen,
                                                             int prefDepth);
    unsigned long       xlib_rgb_xpixel_from_rgb            (guint32 rgb);
    void                xlib_rgb_gc_set_foreground          (GC gc,
                                                             guint32 rgb);
    void                xlib_rgb_gc_set_background          (GC gc,
                                                             guint32 rgb);
    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);
    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);
    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);
    void                xlib_draw_gray_image                (Drawable drawable,
                                                             GC gc,
                                                             int x,
                                                             int y,
                                                             int width,
                                                             int height,
                                                             XlibRgbDither dith,
                                                             unsigned char *buf,
                                                             int rowstride);
    XlibRgbCmap *       xlib_rgb_cmap_new                   (guint32 *colors,
                                                             int n_colors);
    void                xlib_rgb_cmap_free                  (XlibRgbCmap *cmap);
    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);
    Bool                xlib_rgb_ditherable                 (void);
    void                xlib_rgb_set_verbose                (Bool verbose);
    void                xlib_rgb_set_install                (Bool install);
    void                xlib_rgb_set_min_colors             (int min_colors);
    Colormap            xlib_rgb_get_cmap                   (void);
    Visual *            xlib_rgb_get_visual                 (void);
    XVisualInfo *       xlib_rgb_get_visual_info            (void);
    int                 xlib_rgb_get_depth                  (void);
    Display *           xlib_rgb_get_display                (void);
    Screen *            xlib_rgb_get_screen                 (void);

## 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.

## Details

### XlibRgbCmap

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

FIXME: Describe this.

unsigned int colors[256];

  FIXME.

unsigned char lut[256];

  FIXME.

### enum XlibRgbDither

    typedef enum
    {
      XLIB_RGB_DITHER_NONE,
      XLIB_RGB_DITHER_NORMAL,
      XLIB_RGB_DITHER_MAX
    } 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.

`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.

### 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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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

`colors` :

  FIXME

`n_colors` :

  FIXME

Returns :

  FIXME

### xlib_rgb_cmap_free ()

    void                xlib_rgb_cmap_free                  (XlibRgbCmap *cmap);

Frees an XlibRGB colormap.

`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

`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.

`verbose` :

  `True` to be verbose

### xlib_rgb_set_install ()

    void                xlib_rgb_set_install                (Bool install);

Sets whether we install an RGB colormap.

`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.

`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.

## See Also

GdkRGB