XlibRGB

XlibRGB — Rendering RGB buffers to X drawables.

Functions

Types and Values

Includes

#include <gdk-pixbuf/gdk-pixbuf.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. <symbol>XLIB_RGB_DITHER_NONE</symbol> will use no dithering and simply map the colors in an RGB buffer to the closest colors that the display can provide. <symbol>XLIB_RGB_DITHER_NORMAL</symbol> will provide dithering only on pseudocolor displays. <symbol>XLIB_RGB_DITHER_MAX</symbol> 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.

 

See Also

GdkRGB