# Cairo::ImageSurface Class Reference

Image surfaces provide the ability to render to memory buffers either allocated by cairo or by the calling code. More...

Inheritance diagram for Cairo::ImageSurface:
[legend]

List of all members.

## Public Member Functions

| ImageSurface (cairo_surface_t*cobject, bool has_reference=false)
| Create a C++ wrapper for the C instance.
virtual | ~ImageSurface ()
int | get_width () const
| Gets the width of the ImageSurface in pixels.
int | get_height () const
| Gets the height of the ImageSurface in pixels.
unsigned char* | get_data ()
| Get a pointer to the data of the image surface, for direct inspection or modification.
const unsigned char* | get_data () const
Format | get_format () const
| gets the format of the surface
int | get_stride () const
| Return value: the stride of the image surface in bytes (or 0 if is not an image surface).

## Static Public Member Functions

static int | format_stride_for_width (Cairo::Format format, int width)
| This function provides a stride value that will respect all alignment requirements of the accelerated image-rendering code within cairo.
static RefPtr< ImageSurface > | create (Format format, int width, int height)
| Creates an image surface of the specified format and dimensions.
static RefPtr< ImageSurface > | create (unsigned char* data, Format format, int width, int height, int stride)
| Creates an image surface for the provided pixel data.
static RefPtr< ImageSurface > | create_from_png (std::string filename)
| Creates a new image surface and initializes the contents to the given PNG file.
static RefPtr< ImageSurface > | create_from_png_stream (const SlotReadFunc& read_func)
| Creates a new image surface from PNG data read incrementally via the read_func function.
static RefPtr< ImageSurface > | create_from_png (cairo_read_func_t read_func, void* closure)

## Detailed Description

Image surfaces provide the ability to render to memory buffers either allocated by cairo or by the calling code.

The supported image formats are those defined in Cairo::Format

An ImageSurface is the most generic type of Surface and the only one that is available by default. You can either create an ImageSurface whose data is managed by Cairo, or you can create an ImageSurface with a data buffer that you allocated yourself so that you can have full access to the data.

When you create an ImageSurface with your own data buffer, you are free to examine the results at any point and do whatever you want with it. Note that if you modify anything and later want to continue to draw to the surface with cairo, you must let cairo know via Cairo::Surface::mark_dirty()

Note that like all surfaces, an ImageSurface is a reference-counted object that should be used via Cairo::RefPtr.

## Constructor & Destructor Documentation

Cairo::ImageSurface::ImageSurface | ( | cairo_surface_t * | cobject,
|  | bool | has_reference = `false`
| ) |  | `[explicit]`

Create a C++ wrapper for the C instance.

This C++ instance should then be given to a RefPtr.

Parameters:

  cobject | The C instance.
  has_reference | Whether we already have a reference. Otherwise, the constructor will take an extra reference.

virtual Cairo::ImageSurface::~ImageSurface | ( |  | ) | `[virtual]`

## Member Function Documentation

static RefPtr<ImageSurface> Cairo::ImageSurface::create | ( | Format | format,
|  | int | width,
|  | int | height
| ) |  | `[static]`

Creates an image surface of the specified format and dimensions.

Initially the surface contents are all 0. (Specifically, within each pixel, each color or alpha channel belonging to format will be 0. The contents of bits within a pixel, but not belonging to the given format are undefined).

Parameters:

  format | format of pixels in the surface to create
  width | width of the surface, in pixels
  height | height of the surface, in pixels

Returns:
  a RefPtr to the newly created surface.

Examples:
  image-surface.cc, toy-text.cc, and user-font.cc.

static RefPtr<ImageSurface> Cairo::ImageSurface::create | ( | unsigned char * | data,
|  | Format | format,
|  | int | width,
|  | int | height,
|  | int | stride
| ) |  | `[static]`

Creates an image surface for the provided pixel data.

The output buffer must be kept around until the surface is destroyed or finish() is called on the surface. The initial contents of buffer will be used as the initial image contents; you must explicitly clear the buffer, using, for example, Context::rectangle() and Context::fill() if you want it cleared.

Note that the stride may be larger than width* bytes_per_pixel to provide proper alignment for each pixel and row. This alignment is required to allow high-performance rendering within cairo. The correct way to obtain a legal stride value is to call format_stride_for_width() with the desired format and maximum image width value, and the use the resulting stride value to allocate the data and to create the image surface. See format_stride_for_width() for example code.

Parameters:

  data | a pointer to a buffer supplied by the application in which to write contents. This pointer must be suitably aligned for any kind of variable, (for example, a pointer returned by malloc).
  format | the format of pixels in the buffer
  width | the width of the image to be stored in the buffer
  height | the height of the image to be stored in the buffer
  stride | the number of bytes between the start of rows in the buffer as allocated. This value should always be computed by cairo_format_stride_for_width() before allocating the data buffer.

Returns:
  a RefPtr to the newly created surface.

static RefPtr<ImageSurface> Cairo::ImageSurface::create_from_png | ( | std::string | filename | ) | `[static]`

Creates a new image surface and initializes the contents to the given PNG file.

Note:
  For this function to be available, cairo must have been compiled with PNG support.

Parameters:

  filename | name of PNG file to load

Returns:
  a RefPtr to the new cairo_surface_t initialized with the contents of the PNG image file.

static RefPtr<ImageSurface> Cairo::ImageSurface::create_from_png | ( | cairo_read_func_t | read_func,
|  | void * | closure
| ) |  | `[static]`

Deprecated:
  Use create_from_png_stream instead

static RefPtr<ImageSurface> Cairo::ImageSurface::create_from_png_stream | ( | const SlotReadFunc & | read_func | ) | `[static]`

Creates a new image surface from PNG data read incrementally via the read_func function.

Note:
  For this function to be available, cairo must have been compiled with PNG support.

Parameters:

  read_func | function called to read the data of the file

Returns:
  a RefPtr to the new cairo_surface_t initialized with the contents of the PNG image file.

static int Cairo::ImageSurface::format_stride_for_width | ( | Cairo::Format | format,
|  | int | width
| ) |  | `[static]`

This function provides a stride value that will respect all alignment requirements of the accelerated image-rendering code within cairo.

Typical usage will be of the form:

     int stride;
     unsigned char *data;
     Cairo::RefPtr<Cairo::ImageSurface> surface;

     stride = Cairo::ImageSurface::format_stride_for_width (format, width);
     data = malloc (stride * height);
     surface = Cairo::ImageSurface::create (data, format, width, height);

Parameters:

  format | A Cairo::Format value
  width | The desired width of an image surface to be created.

Returns:
  the appropriate stride to use given the desired format and width, or -1 if either the format is invalid or the width too large.

Since:
  1.6

const unsigned char* Cairo::ImageSurface::get_data | ( |  | ) | const

unsigned char* Cairo::ImageSurface::get_data | ( |  | ) |

Get a pointer to the data of the image surface, for direct inspection or modification.

Return value: a pointer to the image data of this surface or NULL if is not an image surface.

Format Cairo::ImageSurface::get_format | ( |  | ) | const

gets the format of the surface

int Cairo::ImageSurface::get_height | ( |  | ) | const

Gets the height of the ImageSurface in pixels.

int Cairo::ImageSurface::get_stride | ( |  | ) | const

Return value: the stride of the image surface in bytes (or 0 if is not an image surface).

The stride is the distance in bytes from the beginning of one row of the image data to the beginning of the next row.

int Cairo::ImageSurface::get_width | ( |  | ) | const

Gets the width of the ImageSurface in pixels.

The documentation for this class was generated from the following file:

- cairomm/surface.h