The libart library
<<< Previous Page | Home | Up | Next Page >>>

# Pixel Buffers

## Name

Pixel Buffers --

## Synopsis

    void        (*ArtDestroyNotify)             (void *func_data,
                                                 void *data);
    struct      ArtPixBuf;
    enum        ArtPixFormat;
    ArtPixBuf*  art_pixbuf_new_rgb              (art_u8 *pixels,
                                                 int width,
                                                 int height,
                                                 int rowstride);
    ArtPixBuf*  art_pixbuf_new_rgba             (art_u8 *pixels,
                                                 int width,
                                                 int height,
                                                 int rowstride);
    ArtPixBuf*  art_pixbuf_new_const_rgb        (const art_u8 *pixels,
                                                 int width,
                                                 int height,
                                                 int rowstride);
    ArtPixBuf*  art_pixbuf_new_const_rgba       (const art_u8 *pixels,
                                                 int width,
                                                 int height,
                                                 int rowstride);
    ArtPixBuf*  art_pixbuf_new_rgb_dnotify      (art_u8 *pixels,
                                                 int width,
                                                 int height,
                                                 int rowstride,
                                                 void *dfunc_data,
                                                 ArtDestroyNotify dfunc);
    ArtPixBuf*  art_pixbuf_new_rgba_dnotify     (art_u8 *pixels,
                                                 int width,
                                                 int height,
                                                 int rowstride,
                                                 void *dfunc_data,
                                                 ArtDestroyNotify dfunc);
    void        art_pixbuf_free                 (ArtPixBuf *pixbuf);
    void        art_pixbuf_free_shallow         (ArtPixBuf *pixbuf);
    ArtPixBuf*  art_pixbuf_duplicate            (const ArtPixBuf *pixbuf);

## Description

## Details

### ArtDestroyNotify ()

    void        (*ArtDestroyNotify)             (void *func_data,
                                                 void *data);

`func_data` : |
`data` : |

### struct ArtPixBuf

    struct ArtPixBuf {
      /*< public >*/
      ArtPixFormat format;
      int n_channels;
      int has_alpha;
      int bits_per_sample;

      art_u8 *pixels;
      int width;
      int height;
      int rowstride;
      void *destroy_data;
      ArtDestroyNotify destroy;
    };

### enum ArtPixFormat

    typedef enum {
      ART_PIX_RGB
      /* gray, cmyk, lab, ... ? */
    } ArtPixFormat;

### art_pixbuf_new_rgb ()

    ArtPixBuf*  art_pixbuf_new_rgb              (art_u8 *pixels,
                                                 int width,
                                                 int height,
                                                 int rowstride);

Creates a generic data structure for holding a buffer of RGB pixels. It is possible to think of an ArtPixBuf as a virtualization over specific pixel buffer formats.

The `pixels` buffer is freed with art_free() when the ArtPixBuf is destroyed. Thus, this function is suitable when the pixel data is allocated with art_alloc().

`pixels` : | A buffer containing the actual pixel data.
`width` : | The width of the pixbuf.
`height` : | The height of the pixbuf.
`rowstride` : | The rowstride of the pixbuf.
Returns : | The newly created ArtPixBuf.

### art_pixbuf_new_rgba ()

    ArtPixBuf*  art_pixbuf_new_rgba             (art_u8 *pixels,
                                                 int width,
                                                 int height,
                                                 int rowstride);

Creates a generic data structure for holding a buffer of RGBA pixels. It is possible to think of an ArtPixBuf as a virtualization over specific pixel buffer formats.

The `pixels` buffer is freed with art_free() when the ArtPixBuf is destroyed. Thus, this function is suitable when the pixel data is allocated with art_alloc().

`pixels` : | A buffer containing the actual pixel data.
`width` : | The width of the pixbuf.
`height` : | The height of the pixbuf.
`rowstride` : | The rowstride of the pixbuf.
Returns : | The newly created ArtPixBuf.

### art_pixbuf_new_const_rgb ()

    ArtPixBuf*  art_pixbuf_new_const_rgb        (const art_u8 *pixels,
                                                 int width,
                                                 int height,
                                                 int rowstride);

Creates a generic data structure for holding a buffer of RGB pixels. It is possible to think of an ArtPixBuf as a virtualization over specific pixel buffer formats.

No action is taken when the ArtPixBuf is destroyed. Thus, this function is useful when the pixel data is constant or statically allocated.

`pixels` : | A buffer containing the actual pixel data.
`width` : | The width of the pixbuf.
`height` : | The height of the pixbuf.
`rowstride` : | The rowstride of the pixbuf.
Returns : | The newly created ArtPixBuf.

### art_pixbuf_new_const_rgba ()

    ArtPixBuf*  art_pixbuf_new_const_rgba       (const art_u8 *pixels,
                                                 int width,
                                                 int height,
                                                 int rowstride);

Creates a generic data structure for holding a buffer of RGBA pixels. It is possible to think of an ArtPixBuf as a virtualization over specific pixel buffer formats.

No action is taken when the ArtPixBuf is destroyed. Thus, this function is suitable when the pixel data is constant or statically allocated.

`pixels` : | A buffer containing the actual pixel data.
`width` : | The width of the pixbuf.
`height` : | The height of the pixbuf.
`rowstride` : | The rowstride of the pixbuf.
Returns : | The newly created ArtPixBuf.

### art_pixbuf_new_rgb_dnotify ()

    ArtPixBuf*  art_pixbuf_new_rgb_dnotify      (art_u8 *pixels,
                                                 int width,
                                                 int height,
                                                 int rowstride,
                                                 void *dfunc_data,
                                                 ArtDestroyNotify dfunc);

Creates a generic data structure for holding a buffer of RGB pixels. It is possible to think of an ArtPixBuf as a virtualization over specific pixel buffer formats.

`dfunc` is called with `dfunc_data` and `pixels` as arguments when the ArtPixBuf is destroyed. Using a destroy notification function allows a wide range of memory management disciplines for the pixel memory. A NULL value for `dfunc` is also allowed and means that no special action will be taken on destruction.

`pixels` : | A buffer containing the actual pixel data.
`width` : | The width of the pixbuf.
`height` : | The height of the pixbuf.
`rowstride` : | The rowstride of the pixbuf.
`dfunc_data` : | The private data passed to `dfunc`.
`dfunc` : | The destroy notification function.
Returns : | The newly created ArtPixBuf.

### art_pixbuf_new_rgba_dnotify ()

    ArtPixBuf*  art_pixbuf_new_rgba_dnotify     (art_u8 *pixels,
                                                 int width,
                                                 int height,
                                                 int rowstride,
                                                 void *dfunc_data,
                                                 ArtDestroyNotify dfunc);

Creates a generic data structure for holding a buffer of RGBA pixels. It is possible to think of an ArtPixBuf as a virtualization over specific pixel buffer formats.

`dfunc` is called with `dfunc_data` and `pixels` as arguments when the ArtPixBuf is destroyed. Using a destroy notification function allows a wide range of memory management disciplines for the pixel memory. A NULL value for `dfunc` is also allowed and means that no special action will be taken on destruction.

`pixels` : | A buffer containing the actual pixel data.
`width` : | The width of the pixbuf.
`height` : | The height of the pixbuf.
`rowstride` : | The rowstride of the pixbuf.
`dfunc_data` : | The private data passed to `dfunc`.
`dfunc` : | The destroy notification function.
Returns : | The newly created ArtPixBuf.

### art_pixbuf_free ()

    void        art_pixbuf_free                 (ArtPixBuf *pixbuf);

Destroys the ArtPixBuf, calling the destroy notification function (if non-NULL) so that the memory for the pixel buffer can be properly reclaimed.

`pixbuf` : | The ArtPixBuf to be destroyed.

### art_pixbuf_free_shallow ()

    void        art_pixbuf_free_shallow         (ArtPixBuf *pixbuf);

Destroys the ArtPixBuf without calling the destroy notification function.

This function is deprecated. Use the _dnotify variants for allocation instead.

`pixbuf` : | The ArtPixBuf to be destroyed.

### art_pixbuf_duplicate ()

    ArtPixBuf*  art_pixbuf_duplicate            (const ArtPixBuf *pixbuf);

Duplicates a pixbuf, including duplicating the buffer.

`pixbuf` : | The ArtPixBuf to duplicate.
Returns : | The duplicated pixbuf.

<<< Previous Page | Home | Up | Next Page >>>
Advanced APIs | Pixel buffer affine transformations