jpayne@68: jpayne@68: jpayne@68:
jpayne@68: jpayne@68:jpayne@68: Top jpayne@68: | jpayne@68:![]() |
jpayne@68: ![]() |
jpayne@68: ![]() |
jpayne@68: ![]() |
jpayne@68:
jpayne@68: Image Surfacesjpayne@68:Image Surfaces — Rendering to memory buffers jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: int jpayne@68: | jpayne@68:jpayne@68: cairo_format_stride_for_width () jpayne@68: | jpayne@68:
jpayne@68: cairo_surface_t * jpayne@68: | jpayne@68:jpayne@68: cairo_image_surface_create () jpayne@68: | jpayne@68:
jpayne@68: cairo_surface_t * jpayne@68: | jpayne@68:jpayne@68: cairo_image_surface_create_for_data () jpayne@68: | jpayne@68:
unsigned char * jpayne@68: | jpayne@68:jpayne@68: cairo_image_surface_get_data () jpayne@68: | jpayne@68:
jpayne@68: cairo_format_t jpayne@68: | jpayne@68:jpayne@68: cairo_image_surface_get_format () jpayne@68: | jpayne@68:
jpayne@68: int jpayne@68: | jpayne@68:jpayne@68: cairo_image_surface_get_width () jpayne@68: | jpayne@68:
jpayne@68: int jpayne@68: | jpayne@68:jpayne@68: cairo_image_surface_get_height () jpayne@68: | jpayne@68:
jpayne@68: int jpayne@68: | jpayne@68:jpayne@68: cairo_image_surface_get_stride () jpayne@68: | jpayne@68:
#define | jpayne@68:CAIRO_HAS_IMAGE_SURFACE | jpayne@68:
enum | jpayne@68:cairo_format_t | jpayne@68:
Image surfaces provide the ability to render to memory buffers jpayne@68: either allocated by cairo or by the calling code. The supported jpayne@68: image formats are those defined in cairo_format_t.
jpayne@68:int jpayne@68: cairo_format_stride_for_width (jpayne@68:cairo_format_t format
, jpayne@68:int width
);
This function provides a stride value that will respect all jpayne@68: alignment requirements of the accelerated image-rendering code jpayne@68: within cairo. Typical usage will be of the form:
jpayne@68:1 jpayne@68: 2 jpayne@68: 3 jpayne@68: 4 jpayne@68: 5 jpayne@68: 6 jpayne@68: 7 jpayne@68: 8 jpayne@68: 9 |
jpayne@68: int stride; jpayne@68: unsigned char *data; jpayne@68: cairo_surface_t *surface; jpayne@68: jpayne@68: stride = cairo_format_stride_for_width (format, width); jpayne@68: data = malloc (stride * height); jpayne@68: surface = cairo_image_surface_create_for_data (data, format, jpayne@68: width, height, jpayne@68: stride); |
jpayne@68:
format |
jpayne@68: A cairo_format_t value |
jpayne@68: jpayne@68: |
width |
jpayne@68: The desired width of an image surface to be created. |
jpayne@68: jpayne@68: |
the appropriate stride to use given the desired jpayne@68: format and width, or -1 if either the format is invalid or the width jpayne@68: too large.
jpayne@68:Since: 1.6
jpayne@68:cairo_surface_t * jpayne@68: cairo_image_surface_create (jpayne@68:cairo_format_t format
, jpayne@68:int width
, jpayne@68:int height
);
Creates an image surface of the specified format and jpayne@68: dimensions. Initially the surface contents are set to 0. jpayne@68: (Specifically, within each pixel, each color or alpha channel jpayne@68: belonging to format will be 0. The contents of bits within a pixel, jpayne@68: but not belonging to the given format are undefined).
jpayne@68:format |
jpayne@68: format of pixels in the surface to create |
jpayne@68: jpayne@68: |
width |
jpayne@68: width of the surface, in pixels |
jpayne@68: jpayne@68: |
height |
jpayne@68: height of the surface, in pixels |
jpayne@68: jpayne@68: |
a pointer to the newly created surface. The caller
jpayne@68: owns the surface and should call cairo_surface_destroy()
when done
jpayne@68: with it.
This function always returns a valid pointer, but it will return a
jpayne@68: pointer to a "nil" surface if an error such as out of memory
jpayne@68: occurs. You can use cairo_surface_status()
to check for this.
Since: 1.0
jpayne@68:cairo_surface_t * jpayne@68: cairo_image_surface_create_for_data (jpayne@68:unsigned char *data
, jpayne@68:cairo_format_t format
, jpayne@68:int width
, jpayne@68:int height
, jpayne@68:int stride
);
Creates an image surface for the provided pixel data. The output
jpayne@68: buffer must be kept around until the cairo_surface_t is destroyed
jpayne@68: or cairo_surface_finish()
is called on the surface. The initial
jpayne@68: contents of data
jpayne@68: will be used as the initial image contents; you
jpayne@68: must explicitly clear the buffer, using, for example,
jpayne@68: cairo_rectangle()
and cairo_fill()
if you want it cleared.
Note that the stride may be larger than
jpayne@68: width*bytes_per_pixel to provide proper alignment for each pixel
jpayne@68: and row. This alignment is required to allow high-performance rendering
jpayne@68: within cairo. The correct way to obtain a legal stride value is to
jpayne@68: call cairo_format_stride_for_width()
with the desired format and
jpayne@68: maximum image width value, and then use the resulting stride value
jpayne@68: to allocate the data and to create the image surface. See
jpayne@68: cairo_format_stride_for_width()
for example code.
data |
jpayne@68: a pointer to a buffer supplied by the application in which jpayne@68: to write contents. This pointer must be suitably aligned for any jpayne@68: kind of variable, (for example, a pointer returned by malloc). |
jpayne@68: jpayne@68: |
format |
jpayne@68: the format of pixels in the buffer |
jpayne@68: jpayne@68: |
width |
jpayne@68: the width of the image to be stored in the buffer |
jpayne@68: jpayne@68: |
height |
jpayne@68: the height of the image to be stored in the buffer |
jpayne@68: jpayne@68: |
stride |
jpayne@68: the number of bytes between the start of rows in the
jpayne@68: buffer as allocated. This value should always be computed by
jpayne@68: |
jpayne@68: jpayne@68: |
a pointer to the newly created surface. The caller
jpayne@68: owns the surface and should call cairo_surface_destroy()
when done
jpayne@68: with it.
This function always returns a valid pointer, but it will return a
jpayne@68: pointer to a "nil" surface in the case of an error such as out of
jpayne@68: memory or an invalid stride value. In case of invalid stride value
jpayne@68: the error status of the returned surface will be
jpayne@68: CAIRO_STATUS_INVALID_STRIDE
. You can use
jpayne@68: cairo_surface_status()
to check for this.
See cairo_surface_set_user_data()
for a means of attaching a
jpayne@68: destroy-notification fallback to the surface if necessary.
Since: 1.0
jpayne@68:unsigned char *
jpayne@68: cairo_image_surface_get_data (cairo_surface_t *surface
);
jpayne@68: Get a pointer to the data of the image surface, for direct jpayne@68: inspection or modification.
jpayne@68:A call to cairo_surface_flush()
is required before accessing the
jpayne@68: pixel data to ensure that all pending drawing operations are
jpayne@68: finished. A call to cairo_surface_mark_dirty()
is required after
jpayne@68: the data is modified.
surface |
jpayne@68: a cairo_image_surface_t |
jpayne@68: jpayne@68: |
a pointer to the image data of this surface or NULL
jpayne@68: if surface
jpayne@68: is not an image surface, or if cairo_surface_finish()
jpayne@68: has been called.
Since: 1.2
jpayne@68:cairo_format_t
jpayne@68: cairo_image_surface_get_format (cairo_surface_t *surface
);
jpayne@68: Get the format of the surface.
jpayne@68:surface |
jpayne@68: a cairo_image_surface_t |
jpayne@68: jpayne@68: |
Since: 1.2
jpayne@68:int
jpayne@68: cairo_image_surface_get_width (cairo_surface_t *surface
);
jpayne@68: Get the width of the image surface in pixels.
jpayne@68:surface |
jpayne@68: a cairo_image_surface_t |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:int
jpayne@68: cairo_image_surface_get_height (cairo_surface_t *surface
);
jpayne@68: Get the height of the image surface in pixels.
jpayne@68:surface |
jpayne@68: a cairo_image_surface_t |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:int
jpayne@68: cairo_image_surface_get_stride (cairo_surface_t *surface
);
jpayne@68: Get the stride of the image surface in bytes
jpayne@68:surface |
jpayne@68: a cairo_image_surface_t |
jpayne@68: jpayne@68: |
the stride of the image surface in bytes (or 0 if
jpayne@68: surface
jpayne@68: is not an image surface). The stride is the distance in
jpayne@68: bytes from the beginning of one row of the image data to the
jpayne@68: beginning of the next row.
Since: 1.2
jpayne@68:#define CAIRO_HAS_IMAGE_SURFACE 1 jpayne@68:jpayne@68:
Defined if the image surface backend is available. jpayne@68: The image surface backend is always built in. jpayne@68: This macro was added for completeness in cairo 1.8.
jpayne@68:Since: 1.8
jpayne@68:cairo_format_t is used to identify the memory format of jpayne@68: image data.
jpayne@68:New entries may be added in future versions.
jpayne@68:jpayne@68: |
jpayne@68: no such format exists or is supported. jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: each pixel is a 32-bit quantity, with jpayne@68: alpha in the upper 8 bits, then red, then green, then blue. jpayne@68: The 32-bit quantities are stored native-endian. Pre-multiplied jpayne@68: alpha is used. (That is, 50% transparent red is 0x80800000, jpayne@68: not 0x80ff0000.) (Since 1.0) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: each pixel is a 32-bit quantity, with jpayne@68: the upper 8 bits unused. Red, Green, and Blue are stored jpayne@68: in the remaining 24 bits in that order. (Since 1.0) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: each pixel is a 8-bit quantity holding jpayne@68: an alpha value. (Since 1.0) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: each pixel is a 1-bit quantity holding jpayne@68: an alpha value. Pixels are packed together into 32-bit jpayne@68: quantities. The ordering of the bits matches the jpayne@68: endianness of the platform. On a big-endian machine, the jpayne@68: first pixel is in the uppermost bit, on a little-endian jpayne@68: machine the first pixel is in the least-significant bit. (Since 1.0) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: each pixel is a 16-bit quantity jpayne@68: with red in the upper 5 bits, then green in the middle jpayne@68: 6 bits, and blue in the lower 5 bits. (Since 1.2) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: like RGB24 but with 10bpc. (Since 1.12) jpayne@68: |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68: