MBPixbuf - Simple image manipulation tools

mbpixbuf contains simple image manipulation and composition functions for client side images. More...

## Macros

#define | mb_pixbuf_img_set_pixel(i, x, y, r, g, b)
| DEPRICIATED.
#define | mb_pixbuf_img_set_pixel_alpha(i, x, y, a)
| sets a pixels alpha value
#define | mb_pixbuf_img_get_width(image) (image)->width
| returns image width
#define | mb_pixbuf_img_get_height(image) (image)->height
| returns image height
#define | mb_pixbuf_get_depth(pb) (pb)->depth
| returns pixbuf instance depth
#define | mb_pixbuf_img_has_alpha(image) (image)->has_alpha
| Returns True if image has an alpha channel.

## Typedefs

typedef struct MBPixbuf | MBPixbuf
| Opaque structure used for all operations.
typedef struct MBPixbufImage | MBPixbufImage
| Type for representing an mbpixbuf image.

## Enumerations

enum | MBPixbufTransform
| enumerated types for mb_pixbuf_img_transform

## Functions

MBPixbuf * | mb_pixbuf_new (Display *display, int screen)
| Constructs a new MBPixbuf instance.
MBPixbuf * | mb_pixbuf_new_extended (Display *dpy, int scr, Visual *vis, int depth)
| Constructs a new MBPixbuf instance with non default depth and visual.
void | mb_pixbuf_destroy (MBPixbuf *pixbuf)
| Destroys a new MBPixbuf instance.
unsigned long | mb_pixbuf_lookup_x_pixel (MBPixbuf *pixbuf, int r, int g, int b, int a)
| Get the X pixel representation for a given color.
MBPixbufImage * | mb_pixbuf_img_new (MBPixbuf *pb, int width, int height)
| DEPRECIATED.
MBPixbufImage * | mb_pixbuf_img_rgba_new (MBPixbuf *pixbuf, int width, int height)
| Constructs a new blank mbpixbuf image with an alpha channel.
MBPixbufImage * | mb_pixbuf_img_rgb_new (MBPixbuf *pixbuf, int width, int height)
| Constructs a new blank mbpixbuf image without an alpha channel.
MBPixbufImage * | mb_pixbuf_img_new_from_drawable (MBPixbuf *pixbuf, Drawable drawable, Drawable mask, int source_x, int source_y, int source_w, int source_h)
| Depreicated.
MBPixbufImage * | mb_pixbuf_img_new_from_x_drawable (MBPixbuf *pixbuf, Drawable drawable, Drawable mask, int source_x, int source_y, int source_w, int source_h, Bool want_alpha)
| Constructs a new blank mbpixbuf image with/without an alpha channel.
MBPixbufImage * | mb_pixbuf_img_new_from_file (MBPixbuf *pixbuf, const char *filename)
| Creates an mbpixbuf image from a file on disk.
MBPixbufImage * | mb_pixbuf_img_new_from_data (MBPixbuf *pixbuf, const unsigned char *data, int width, int height, Bool has_alpha)
| Creates an mbpixbuf image from arbituary supplied rgb(a) data.
MBPixbufImage * | mb_pixbuf_img_new_from_int_data (MBPixbuf *pixbuf, const int *data, int width, int height)
| Creates an mbpixbuf image from arbituary supplied INT ARGB data.
MBPixbufImage * | mb_pixbuf_img_new_from_long_data (MBPixbuf *pixbuf, const unsigned long *data, int width, int height)
| Creates an mbpixbuf image from arbituary supplied long ARGB data.
void | mb_pixbuf_img_free (MBPixbuf *pixbuf, MBPixbufImage *image)
| Frees up a mbpixbuf image.
void | mb_pixbuf_img_render_to_drawable (MBPixbuf *pixbuf, MBPixbufImage *image, Drawable drw, int drw_x, int drw_y)
| Renders a mbpixbuf image to an X Drawable.
void | mb_pixbuf_img_render_to_drawable_with_gc (MBPixbuf *pixbuf, MBPixbufImage *image, Drawable drw, int drw_x, int drw_y, GC gc)
| Renders a mbpixbuf image to an X Drawable with a specified.
void | mb_pixbuf_img_render_to_mask (MBPixbuf *pixbuf, MBPixbufImage *image, Drawable mask, int mask_x, int mask_y)
| Renders alpha component mbpixbuf image to an X Bitmap.
MBPixbufImage * | mb_pixbuf_img_clone (MBPixbuf *pixbuf, MBPixbufImage *image)
| Clones a exisiting mbpixbuf image.
void | mb_pixbuf_img_fill (MBPixbuf *pixbuf, MBPixbufImage *image, int r, int g, int b, int a)
| Fills an image with specified color / alpha level.
void | mb_pixbuf_img_plot_pixel (MBPixbuf *pixbuf, MBPixbufImage *image, int x, int y, unsigned char r, unsigned char g, unsigned char b)
| Plots a pixel on specified image.
void | mb_pixbuf_img_get_pixel (MBPixbuf *pixbuf, MBPixbufImage *image, int x, int y, unsigned char *r, unsigned char *g, unsigned char *b, unsigned char *a)
| Gets the component values for a specified pixel.
unsigned char * | mb_pixbuf_img_data (MBPixbuf *pixbuf, MBPixbufImage *image)
| Gets rgb(a) internal data representation of an image.
void | mb_pixbuf_img_plot_pixel_with_alpha (MBPixbuf *pixbuf, MBPixbufImage *image, int x, int y, unsigned char r, unsigned char g, unsigned char b, unsigned char a)
| Plots a pixel on specified image with alpha channel value.
void | mb_pixbuf_img_copy (MBPixbuf *pixbuf, MBPixbufImage *dest, MBPixbufImage *src, int sx, int sy, int sw, int sh, int dx, int dy)
| Copys an specified area of an image to another.
void | mb_pixbuf_img_copy_composite (MBPixbuf *pixbuf, MBPixbufImage *dest, MBPixbufImage *src, int sx, int sy, int sw, int sh, int dx, int dy)
| Alpha composites an specified area of an image with another.
void | mb_pixbuf_img_copy_composite_with_alpha (MBPixbuf *pixbuf, MBPixbufImage *dest, MBPixbufImage *src, int sx, int sy, int sw, int sh, int dx, int dy, int overall_alpha)
| Like mb_pixbuf_img_copy_composite but sets an overall alpha value.
void | mb_pixbuf_img_composite (MBPixbuf *pb, MBPixbufImage *dest, MBPixbufImage *src, int dx, int dy)
| DEPRECATED.
MBPixbufImage * | mb_pixbuf_img_scale (MBPixbuf *pixbuf, MBPixbufImage *image, int new_width, int new_height)
| Scales an image arbitually.
MBPixbufImage * | mb_pixbuf_img_transform (MBPixbuf *pixbuf, MBPixbufImage *image, MBPixbufTransform transform)
| Performs a basic transform on an image.

## Detailed Description

mbpixbuf contains simple image manipulation and composition functions for client side images.

Example: Simple example to load an image and display it on root window.

     #include <libmb/mb.h>

     int
     main(int argc, char **argv)
     {
       Display       *dpy;
       Window         win_root;
       XEvent         xevent;
       MBPixbufImage *img, *img_scaled;
       MBPixbuf      *pb;

       if (argc < 2)
         { fprintf(stderr, "usage: %s image file\\n", argv[0]); exit(1); }

       dpy = XOpenDisplay(NULL);

       pb = mb_pixbuf_new(dpy, DefaultScreen(dpy));

       img = mb_pixbuf_img_new_from_file(pb, argv[1]);

       if (!img) { fprintf(stderr, "image load failed\\n"); exit(1); }

       img_scaled = mb_pixbuf_img_scale(pb, img,
                                        DisplayWidth(dpy), DisplayHeight(dpy));

       if (!img_scaled) { fprintf(stderr, "image scale failed\\n"); exit(1); }

       mb_pixbuf_img_free(pb, img);

       mb_pixbuf_img_render_to_drawable(pb, img_scaled,
                                        RootWindow(dpy, DefaultScreen(dpy))
                                 0, 0);
       for (;;)
          XNextEvent(dpy, &xevent);

       exit(0);
     }

Notes: if the enviromental varible 'MBPIXBUF_NO_SHM' is set, the MIT-SHM extension will not be used.

## Macro Definition Documentation

## mb_pixbuf_img_set_pixel

#define mb_pixbuf_img_set_pixel | ( |  | i,
|  |  | x,
|  |  | y,
|  |  | r,
|  |  | g,
|  |  | b
| ) |  |

Value:
{ \
(i)->rgba[(((y)*(i)->width*4)+((x)*4))] = r; \
(i)->rgba[(((y)*(i)->width*4)+((x)*4))+1] = g; \
(i)->rgba[(((y)*(i)->width*4)+((x)*4))+2] = b; \
(i)->rgba[(((y)*(i)->width*4)+((x)*4))+3] = 0; \
}

DEPRICIATED.

Use mb_pixbuf_img_plot_pixel instead.

Definition at line 179 of file mbpixbuf.h.

## Typedef Documentation

## MBPixbufImage

MBPixbufImage

Type for representing an mbpixbuf image.

Its not recommended you touch this directly.

## Function Documentation

## mb_pixbuf_destroy()

void mb_pixbuf_destroy | ( | MBPixbuf * | pixbuf | ) |

Destroys a new MBPixbuf instance.

Parameters

  pixbuf | MBPixbuf object

## mb_pixbuf_img_clone()

MBPixbufImage * mb_pixbuf_img_clone | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | image
| ) |  |

Clones a exisiting mbpixbuf image.

Parameters

  pixbuf | mbpixbuf object
  image | image to clone

Returns
  a new cloned image

## mb_pixbuf_img_composite()

void mb_pixbuf_img_composite | ( | MBPixbuf * | pb,
|  | MBPixbufImage * | dest,
|  | MBPixbufImage * | src,
|  | int | dx,
|  | int | dy
| ) |  |

DEPRECATED.

Use mb_pixbuf_img_copy_composite instead.

## mb_pixbuf_img_copy()

void mb_pixbuf_img_copy | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | dest,
|  | MBPixbufImage * | src,
|  | int | sx,
|  | int | sy,
|  | int | sw,
|  | int | sh,
|  | int | dx,
|  | int | dy
| ) |  |

Copys an specified area of an image to another.

No Alpha composition is performed.

Parameters

  pixbuf | mbpixbuf object
  dest | destination image
  src | source image
  sx | source area X co-ord
  sy | source area Y co-ord
  sw | source area width.
  sh | source area height.
  dx | destination image X co-ord.
  dy | destination image Y co-ord.

## mb_pixbuf_img_copy_composite()

void mb_pixbuf_img_copy_composite | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | dest,
|  | MBPixbufImage * | src,
|  | int | sx,
|  | int | sy,
|  | int | sw,
|  | int | sh,
|  | int | dx,
|  | int | dy
| ) |  |

Alpha composites an specified area of an image with another.

Parameters

  pixbuf | mbpixbuf object
  dest | destination image
  src | source image
  sx | source area X co-ord
  sy | source area Y co-ord
  sw | source area width.
  sh | source area height.
  dx | destination image X co-ord.
  dy | destination image Y co-ord.

## mb_pixbuf_img_copy_composite_with_alpha()

void mb_pixbuf_img_copy_composite_with_alpha | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | dest,
|  | MBPixbufImage * | src,
|  | int | sx,
|  | int | sy,
|  | int | sw,
|  | int | sh,
|  | int | dx,
|  | int | dy,
|  | int | overall_alpha
| ) |  |

Like mb_pixbuf_img_copy_composite but sets an overall alpha value.

Parameters

  pixbuf | mbpixbuf object
  dest | destination image
  src | source image
  sx | source area X co-ord
  sy | source area Y co-ord
  sw | source area width.
  sh | source area height.
  dx | destination image X co-ord.
  dy | destination image Y co-ord.
  overall_alpha | The overall alpha value to set after composition.

## mb_pixbuf_img_data()

unsigned char * mb_pixbuf_img_data | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | image
| ) |  |

Gets rgb(a) internal data representation of an image.

Parameters

  pixbuf | mbpixbuf object
  image | destination image

Returns
  rgb(a) data

## mb_pixbuf_img_fill()

void mb_pixbuf_img_fill | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | image,
|  | int | r,
|  | int | g,
|  | int | b,
|  | int | a
| ) |  |

Fills an image with specified color / alpha level.

Parameters

  pixbuf | mbpixbuf object
  image | image to fill.
  r | red component of color
  g | green component of color
  b | blue component of color
  a | alpha component

## mb_pixbuf_img_free()

void mb_pixbuf_img_free | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | image
| ) |  |

Frees up a mbpixbuf image.

Parameters

  pixbuf | mbpixbuf object
  image | image to free

## mb_pixbuf_img_get_pixel()

void mb_pixbuf_img_get_pixel | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | image,
|  | int | x,
|  | int | y,
|  | unsigned char * | r,
|  | unsigned char * | g,
|  | unsigned char * | b,
|  | unsigned char * | a
| ) |  |

Gets the component values for a specified pixel.

Parameters

  pixbuf | mbpixbuf object
  image | destination image
  x | X co-ord on destination image
  y | Y co-ord on destination image
  r | red component of color
  g | green component of color
  b | blue component of color
  a | alpha component of pixel

## mb_pixbuf_img_new()

MBPixbufImage * mb_pixbuf_img_new | ( | MBPixbuf * | pb,
|  | int | width,
|  | int | height
| ) |  |

DEPRECIATED.

Use mb_pixbuf_img_rgb_new, mb_pixbuf_img_rgba_new instead.

## mb_pixbuf_img_new_from_data()

MBPixbufImage * mb_pixbuf_img_new_from_data | ( | MBPixbuf * | pixbuf,
|  | const unsigned char * | data,
|  | int | width,
|  | int | height,
|  | Bool | has_alpha
| ) |  |

Creates an mbpixbuf image from arbituary supplied rgb(a) data.

Parameters

  pixbuf | mbpixbuf object
  data | rgb(a) data
  width | image width
  height | image height
  has_alpha | True if data has alpha component

Returns
  a MBPixbufImage object, NULL on faliure

## mb_pixbuf_img_new_from_drawable()

MBPixbufImage * mb_pixbuf_img_new_from_drawable | ( | MBPixbuf * | pixbuf,
|  | Drawable | drawable,
|  | Drawable | mask,
|  | int | source_x,
|  | int | source_y,
|  | int | source_w,
|  | int | source_h
| ) |  |

Depreicated.

use mb_pixbuf_img_new_from_x_drawable instead.

## mb_pixbuf_img_new_from_file()

MBPixbufImage * mb_pixbuf_img_new_from_file | ( | MBPixbuf * | pixbuf,
|  | const char * | filename
| ) |  |

Creates an mbpixbuf image from a file on disk.

Supports PNG, JPEGS and XPMS.

Parameters

  pixbuf | mbpixbuf object
  filename | full filename of image to be loaded

Returns
  a MBPixbufImage object, NULL on faliure

## mb_pixbuf_img_new_from_int_data()

MBPixbufImage * mb_pixbuf_img_new_from_int_data | ( | MBPixbuf * | pixbuf,
|  | const int * | data,
|  | int | width,
|  | int | height
| ) |  |

Creates an mbpixbuf image from arbituary supplied INT ARGB data.

Parameters

  pixbuf | mbpixbuf object
  data | argb data
  width | image width
  height | image height

Returns
  a MBPixbufImage object, NULL on faliure

## mb_pixbuf_img_new_from_long_data()

MBPixbufImage * mb_pixbuf_img_new_from_long_data | ( | MBPixbuf * | pixbuf,
|  | const unsigned long * | data,
|  | int | width,
|  | int | height
| ) |  |

Creates an mbpixbuf image from arbituary supplied long ARGB data.

Useful for example to parse _NET_WM_ICON image data, which XLib kindly returns in long arrays instead of int arrays.

Parameters

  pixbuf | mbpixbuf object
  data | argb data
  width | image width
  height | image height

Returns
  a MBPixbufImage object, NULL on faliure

## mb_pixbuf_img_new_from_x_drawable()

MBPixbufImage * mb_pixbuf_img_new_from_x_drawable | ( | MBPixbuf * | pixbuf,
|  | Drawable | drawable,
|  | Drawable | mask,
|  | int | source_x,
|  | int | source_y,
|  | int | source_w,
|  | int | source_h,
|  | Bool | want_alpha
| ) |  |

Constructs a new blank mbpixbuf image with/without an alpha channel.

Parameters

  pixbuf | mbpixbuf object
  drawable | an X drawable ( window or pixmap )
  mask | set to none if alpha channel not required
  source_x | x co-ord of X drawable
  source_y | y co-ord of X drawable
  source_w | width of X drawable
  source_h | height of X drawable
  want_alpha | force created image to have an ( empty ) alpha channel even if no mask is supplied.

Returns
  a MBPixbufImage object, NULL on faliure

## mb_pixbuf_img_plot_pixel()

void mb_pixbuf_img_plot_pixel | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | image,
|  | int | x,
|  | int | y,
|  | unsigned char | r,
|  | unsigned char | g,
|  | unsigned char | b
| ) |  |

Plots a pixel on specified image.

Note: on a RGBA image the alpha channel is left as-is.

Parameters

  pixbuf | mbpixbuf object
  image | destination image
  x | X co-ord on destination image
  y | Y co-ord on destination image
  r | red component of color
  g | green component of color
  b | blue component of color

## mb_pixbuf_img_plot_pixel_with_alpha()

void mb_pixbuf_img_plot_pixel_with_alpha | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | image,
|  | int | x,
|  | int | y,
|  | unsigned char | r,
|  | unsigned char | g,
|  | unsigned char | b,
|  | unsigned char | a
| ) |  |

Plots a pixel on specified image with alpha channel value.

Parameters

  pixbuf | mbpixbuf object
  image | destination image
  x | X co-ord on destination image
  y | Y co-ord on destination image
  r | red component of color
  g | green component of color
  b | blue component of color
  a | alpha component

## mb_pixbuf_img_render_to_drawable()

void mb_pixbuf_img_render_to_drawable | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | image,
|  | Drawable | drw,
|  | int | drw_x,
|  | int | drw_y
| ) |  |

Renders a mbpixbuf image to an X Drawable.

Parameters

  pixbuf | mbpixbuf object
  image | mbpixbuf image to render
  drw | X11 drawable ( window or pixmap ) to render roo.
  drw_x | X co-ord on drawable to render too.
  drw_y | Y co-ord on drawable to render too.

## mb_pixbuf_img_render_to_drawable_with_gc()

void mb_pixbuf_img_render_to_drawable_with_gc | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | image,
|  | Drawable | drw,
|  | int | drw_x,
|  | int | drw_y,
|  | GC | gc
| ) |  |

Renders a mbpixbuf image to an X Drawable with a specified.

X Graphics Context ( GC ).

Parameters

  pixbuf | mbpixbuf object
  image | mbpixbuf image to render
  drw | X11 drawable ( window or pixmap ) to render roo.
  drw_x | X co-ord on drawable to render too.
  drw_y | Y co-ord on drawable to render too.
  gc | X11 GC to use on drawable.

## mb_pixbuf_img_render_to_mask()

void mb_pixbuf_img_render_to_mask | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | image,
|  | Drawable | mask,
|  | int | mask_x,
|  | int | mask_y
| ) |  |

Renders alpha component mbpixbuf image to an X Bitmap.

Parameters

  pixbuf | mbpixbuf object
  image | mbpixbuf image to render
  mask | X11 bitmap.
  mask_x | X co-ord on drawable to render too.
  mask_y | Y co-ord on drawable to render too.

## mb_pixbuf_img_rgb_new()

MBPixbufImage * mb_pixbuf_img_rgb_new | ( | MBPixbuf * | pixbuf,
|  | int | width,
|  | int | height
| ) |  |

Constructs a new blank mbpixbuf image without an alpha channel.

Parameters

  pixbuf | mbpixbuf object
  width | width in pixels of new image
  height | height in pixels of new image

Returns
  a MBPixbufImage object

## mb_pixbuf_img_rgba_new()

MBPixbufImage * mb_pixbuf_img_rgba_new | ( | MBPixbuf * | pixbuf,
|  | int | width,
|  | int | height
| ) |  |

Constructs a new blank mbpixbuf image with an alpha channel.

Parameters

  pixbuf | mbpixbuf object
  width | width in pixels of new image
  height | height in pixels of new image

Returns
  a MBPixbufImage object

## mb_pixbuf_img_scale()

MBPixbufImage * mb_pixbuf_img_scale | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | image,
|  | int | new_width,
|  | int | new_height
| ) |  |

Scales an image arbitually.

Parameters

  pixbuf | mbpixbuf object
  image | mbpixbuf image to scale
  new_width | new image width
  new_height | new image height

Returns
  a new scaled image

## mb_pixbuf_img_transform()

MBPixbufImage * mb_pixbuf_img_transform | ( | MBPixbuf * | pixbuf,
|  | MBPixbufImage * | image,
|  | MBPixbufTransform | transform
| ) |  |

Performs a basic transform on an image.

Parameters

  pixbuf | mbpixbuf object
  image | mbpixbuf image to scale
  transform | the type of transform to perform

Returns
  a new transformed image

## mb_pixbuf_lookup_x_pixel()

unsigned long mb_pixbuf_lookup_x_pixel | ( | MBPixbuf * | pixbuf,
|  | int | r,
|  | int | g,
|  | int | b,
|  | int | a
| ) |  |

Get the X pixel representation for a given color.

Parameters

  pixbuf | mbpixbuf object
  r | red component of color
  g | green component of color
  b | blue component of color
  a | alpha component

Returns
  x pixel value

## mb_pixbuf_new()

MBPixbuf * mb_pixbuf_new | ( | Display * | display,
|  | int | screen
| ) |  |

Constructs a new MBPixbuf instance.

Parameters

  display |
  screen |

Returns
  a #MBPixbuf object

## mb_pixbuf_new_extended()

MBPixbuf * mb_pixbuf_new_extended | ( | Display * | dpy,
|  | int | scr,
|  | Visual * | vis,
|  | int | depth
| ) |  |

Constructs a new MBPixbuf instance with non default depth and visual.

Parameters

  dpy | X display
  scr | X Screen
  vis | X Visual to use
  depth | Depth to use

Returns
  a #MBPixbuf object