| jpayne@68: Top jpayne@68: | jpayne@68: |
jpayne@68: |
jpayne@68: |
jpayne@68: |
jpayne@68:
jpayne@68: cairo_surface_tjpayne@68:cairo_surface_t — Base class for surfaces jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: cairo_surface_t * jpayne@68: | jpayne@68:jpayne@68: cairo_surface_create_similar () jpayne@68: | jpayne@68:
| jpayne@68: cairo_surface_t * jpayne@68: | jpayne@68:jpayne@68: cairo_surface_create_similar_image () jpayne@68: | jpayne@68:
| jpayne@68: cairo_surface_t * jpayne@68: | jpayne@68:jpayne@68: cairo_surface_create_for_rectangle () jpayne@68: | jpayne@68:
| jpayne@68: cairo_surface_t * jpayne@68: | jpayne@68:jpayne@68: cairo_surface_reference () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_destroy () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_surface_status () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_finish () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_flush () jpayne@68: | jpayne@68:
| jpayne@68: cairo_device_t * jpayne@68: | jpayne@68:jpayne@68: cairo_surface_get_device () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_get_font_options () jpayne@68: | jpayne@68:
| jpayne@68: cairo_content_t jpayne@68: | jpayne@68:jpayne@68: cairo_surface_get_content () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_mark_dirty () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_mark_dirty_rectangle () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_set_device_offset () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_get_device_offset () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_get_device_scale () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_set_device_scale () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_set_fallback_resolution () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_get_fallback_resolution () jpayne@68: | jpayne@68:
| jpayne@68: cairo_surface_type_t jpayne@68: | jpayne@68:jpayne@68: cairo_surface_get_type () jpayne@68: | jpayne@68:
| unsigned int jpayne@68: | jpayne@68:jpayne@68: cairo_surface_get_reference_count () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_surface_set_user_data () jpayne@68: | jpayne@68:
| jpayne@68: void * jpayne@68: | jpayne@68:jpayne@68: cairo_surface_get_user_data () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_copy_page () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_show_page () jpayne@68: | jpayne@68:
| jpayne@68: cairo_bool_t jpayne@68: | jpayne@68:jpayne@68: cairo_surface_has_show_text_glyphs () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_surface_set_mime_data () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_get_mime_data () jpayne@68: | jpayne@68:
| jpayne@68: cairo_bool_t jpayne@68: | jpayne@68:jpayne@68: cairo_surface_supports_mime_type () jpayne@68: | jpayne@68:
| jpayne@68: cairo_surface_t * jpayne@68: | jpayne@68:jpayne@68: cairo_surface_map_to_image () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_surface_unmap_image () jpayne@68: | jpayne@68:
| #define | jpayne@68:CAIRO_HAS_MIME_SURFACE | jpayne@68:
| #define | jpayne@68:CAIRO_MIME_TYPE_CCITT_FAX | jpayne@68:
| #define | jpayne@68:CAIRO_MIME_TYPE_CCITT_FAX_PARAMS | jpayne@68:
| #define | jpayne@68:CAIRO_MIME_TYPE_EPS | jpayne@68:
| #define | jpayne@68:CAIRO_MIME_TYPE_EPS_PARAMS | jpayne@68:
| #define | jpayne@68:CAIRO_MIME_TYPE_JBIG2 | jpayne@68:
| #define | jpayne@68:CAIRO_MIME_TYPE_JBIG2_GLOBAL | jpayne@68:
| #define | jpayne@68:CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID | jpayne@68:
| #define | jpayne@68:CAIRO_MIME_TYPE_JP2 | jpayne@68:
| #define | jpayne@68:CAIRO_MIME_TYPE_JPEG | jpayne@68:
| #define | jpayne@68:CAIRO_MIME_TYPE_PNG | jpayne@68:
| #define | jpayne@68:CAIRO_MIME_TYPE_URI | jpayne@68:
| #define | jpayne@68:CAIRO_MIME_TYPE_UNIQUE_ID | jpayne@68:
| typedef | jpayne@68:cairo_surface_t | jpayne@68:
| enum | jpayne@68:cairo_content_t | jpayne@68:
| enum | jpayne@68:cairo_surface_type_t | jpayne@68:
cairo_surface_t is the abstract type representing all different drawing jpayne@68: targets that cairo can render to. The actual drawings are jpayne@68: performed using a cairo context.
jpayne@68:A cairo surface is created by using backend-specific
jpayne@68: constructors, typically of the form
jpayne@68: cairo_backend_surface_create().
Most surface types allow accessing the surface without using Cairo
jpayne@68: functions. If you do this, keep in mind that it is mandatory that you call
jpayne@68: cairo_surface_flush() before reading from or writing to the surface and that
jpayne@68: you must use cairo_surface_mark_dirty() after modifying it.
Example 1. Directly modifying an image surface
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: 10 jpayne@68: 11 jpayne@68: 12 jpayne@68: 13 jpayne@68: 14 jpayne@68: 15 jpayne@68: 16 jpayne@68: 17 jpayne@68: 18 jpayne@68: 19 |
jpayne@68: void jpayne@68: modify_image_surface (cairo_surface_t *surface) jpayne@68: { jpayne@68: unsigned char *data; jpayne@68: int width, height, stride; jpayne@68: jpayne@68: // flush to ensure all writing to the image was done jpayne@68: cairo_surface_flush (surface); jpayne@68: jpayne@68: // modify the image jpayne@68: data = cairo_image_surface_get_data (surface); jpayne@68: width = cairo_image_surface_get_width (surface); jpayne@68: height = cairo_image_surface_get_height (surface); jpayne@68: stride = cairo_image_surface_get_stride (surface); jpayne@68: modify_image_data (data, width, height, stride); jpayne@68: jpayne@68: // mark the image dirty so Cairo clears its caches. jpayne@68: cairo_surface_mark_dirty (surface); jpayne@68: } |
jpayne@68:
Note that for other surface types it might be necessary to acquire the
jpayne@68: surface's device first. See cairo_device_acquire() for a discussion of
jpayne@68: devices.
cairo_surface_t * jpayne@68: cairo_surface_create_similar (jpayne@68:cairo_surface_t *other, jpayne@68:cairo_content_t content, jpayne@68:int width, jpayne@68:int height);
Create a new surface that is as compatible as possible with an
jpayne@68: existing surface. For example the new surface will have the same
jpayne@68: device scale, fallback resolution and font options as
jpayne@68: other
jpayne@68: . Generally, the new surface will also use the same backend
jpayne@68: as other
jpayne@68: , unless that is not possible for some reason. The type of
jpayne@68: the returned surface may be examined with
jpayne@68: cairo_surface_get_type().
Initially the surface contents are all 0 (transparent if contents jpayne@68: have transparency, black otherwise.)
jpayne@68:Use cairo_surface_create_similar_image() if you need an image surface
jpayne@68: which can be painted quickly to the target surface.
other |
jpayne@68: an existing surface used to select the backend of the new surface |
jpayne@68: jpayne@68: |
content |
jpayne@68: the content for the new surface |
jpayne@68: jpayne@68: |
width |
jpayne@68: width of the new surface, (in device-space units) |
jpayne@68: jpayne@68: |
height |
jpayne@68: height of the new surface (in device-space units) |
jpayne@68: jpayne@68: |
a pointer to the newly allocated 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 other
jpayne@68: is already in an error state
jpayne@68: or any other error occurs.
Since: 1.0
jpayne@68:cairo_surface_t * jpayne@68: cairo_surface_create_similar_image (jpayne@68:cairo_surface_t *other, jpayne@68:cairo_format_t format, jpayne@68:int width, jpayne@68:int height);
Create a new image surface that is as compatible as possible for uploading
jpayne@68: to and the use in conjunction with an existing surface. However, this surface
jpayne@68: can still be used like any normal image surface. Unlike
jpayne@68: cairo_surface_create_similar() the new image surface won't inherit
jpayne@68: the device scale from other
jpayne@68: .
Initially the surface contents are all 0 (transparent if contents jpayne@68: have transparency, black otherwise.)
jpayne@68:Use cairo_surface_create_similar() if you don't need an image surface.
other |
jpayne@68: an existing surface used to select the preference of the new surface |
jpayne@68: jpayne@68: |
format |
jpayne@68: the format for the new surface |
jpayne@68: jpayne@68: |
width |
jpayne@68: width of the new surface, (in pixels) |
jpayne@68: jpayne@68: |
height |
jpayne@68: height of the new surface (in pixels) |
jpayne@68: jpayne@68: |
a pointer to the newly allocated image 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 other
jpayne@68: is already in an error state
jpayne@68: or any other error occurs.
Since: 1.12
jpayne@68:cairo_surface_t * jpayne@68: cairo_surface_create_for_rectangle (jpayne@68:cairo_surface_t *target, jpayne@68:double x, jpayne@68:double y, jpayne@68:double width, jpayne@68:double height);
Create a new surface that is a rectangle within the target surface. jpayne@68: All operations drawn to this surface are then clipped and translated jpayne@68: onto the target surface. Nothing drawn via this sub-surface outside of jpayne@68: its bounds is drawn onto the target surface, making this a useful method jpayne@68: for passing constrained child surfaces to library routines that draw jpayne@68: directly onto the parent surface, i.e. with no further backend allocations, jpayne@68: double buffering or copies.
jpayne@68:The semantics of subsurfaces have not been finalized yet jpayne@68: unless the rectangle is in full device units, is contained within jpayne@68: the extents of the target surface, and the target or subsurface's jpayne@68: device transforms are not changed.
target |
jpayne@68: an existing surface for which the sub-surface will point to |
jpayne@68: jpayne@68: |
x |
jpayne@68: the x-origin of the sub-surface from the top-left of the target surface (in device-space units) |
jpayne@68: jpayne@68: |
y |
jpayne@68: the y-origin of the sub-surface from the top-left of the target surface (in device-space units) |
jpayne@68: jpayne@68: |
width |
jpayne@68: width of the sub-surface (in device-space units) |
jpayne@68: jpayne@68: |
height |
jpayne@68: height of the sub-surface (in device-space units) |
jpayne@68: jpayne@68: |
a pointer to the newly allocated 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 other
jpayne@68: is already in an error state
jpayne@68: or any other error occurs.
Since: 1.10
jpayne@68:cairo_surface_t *
jpayne@68: cairo_surface_reference (cairo_surface_t *surface);
jpayne@68: Increases the reference count on surface
jpayne@68: by one. This prevents
jpayne@68: surface
jpayne@68: from being destroyed until a matching call to
jpayne@68: cairo_surface_destroy() is made.
Use cairo_surface_get_reference_count() to get the number of
jpayne@68: references to a cairo_surface_t.
surface |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.0
jpayne@68:void
jpayne@68: cairo_surface_destroy (cairo_surface_t *surface);
jpayne@68: Decreases the reference count on surface
jpayne@68: by one. If the result is
jpayne@68: zero, then surface
jpayne@68: and all associated resources are freed. See
jpayne@68: cairo_surface_reference().
surface |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.0
jpayne@68:cairo_status_t
jpayne@68: cairo_surface_status (cairo_surface_t *surface);
jpayne@68: Checks whether an error has previously occurred for this jpayne@68: surface.
jpayne@68:surface |
jpayne@68: jpayne@68: | jpayne@68: |
CAIRO_STATUS_SUCCESS, CAIRO_STATUS_NULL_POINTER,
jpayne@68: CAIRO_STATUS_NO_MEMORY, CAIRO_STATUS_READ_ERROR,
jpayne@68: CAIRO_STATUS_INVALID_CONTENT, CAIRO_STATUS_INVALID_FORMAT, or
jpayne@68: CAIRO_STATUS_INVALID_VISUAL.
Since: 1.0
jpayne@68:void
jpayne@68: cairo_surface_finish (cairo_surface_t *surface);
jpayne@68: This function finishes the surface and drops all references to
jpayne@68: external resources. For example, for the Xlib backend it means
jpayne@68: that cairo will no longer access the drawable, which can be freed.
jpayne@68: After calling cairo_surface_finish() the only valid operations on a
jpayne@68: surface are getting and setting user, referencing and
jpayne@68: destroying, and flushing and finishing it.
jpayne@68: Further drawing to the surface will not affect the
jpayne@68: surface but will instead trigger a CAIRO_STATUS_SURFACE_FINISHED
jpayne@68: error.
When the last call to cairo_surface_destroy() decreases the
jpayne@68: reference count to zero, cairo will call cairo_surface_finish() if
jpayne@68: it hasn't been called already, before freeing the resources
jpayne@68: associated with the surface.
surface |
jpayne@68: the cairo_surface_t to finish |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void
jpayne@68: cairo_surface_flush (cairo_surface_t *surface);
jpayne@68: Do any pending drawing for the surface and also restore any temporary jpayne@68: modifications cairo has made to the surface's state. This function jpayne@68: must be called before switching from drawing on the surface with jpayne@68: cairo to drawing on it directly with native APIs, or accessing its jpayne@68: memory outside of Cairo. If the surface doesn't support direct jpayne@68: access, then this function does nothing.
jpayne@68:surface |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.0
jpayne@68:cairo_device_t *
jpayne@68: cairo_surface_get_device (cairo_surface_t *surface);
jpayne@68: This function returns the device for a surface
jpayne@68: .
jpayne@68: See cairo_device_t.
surface |
jpayne@68: jpayne@68: | jpayne@68: |
The device for surface
jpayne@68: or NULL if the surface does
jpayne@68: not have an associated device.
Since: 1.10
jpayne@68:void jpayne@68: cairo_surface_get_font_options (jpayne@68:cairo_surface_t *surface, jpayne@68:cairo_font_options_t *options);
Retrieves the default font rendering options for the surface.
jpayne@68: This allows display surfaces to report the correct subpixel order
jpayne@68: for rendering on them, print surfaces to disable hinting of
jpayne@68: metrics and so forth. The result can then be used with
jpayne@68: cairo_scaled_font_create().
surface |
jpayne@68: jpayne@68: | jpayne@68: |
options |
jpayne@68: a cairo_font_options_t object into which to store jpayne@68: the retrieved options. All existing values are overwritten |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:cairo_content_t
jpayne@68: cairo_surface_get_content (cairo_surface_t *surface);
jpayne@68: This function returns the content type of surface
jpayne@68: which indicates
jpayne@68: whether the surface contains color and/or alpha information. See
jpayne@68: cairo_content_t.
surface |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.2
jpayne@68:void
jpayne@68: cairo_surface_mark_dirty (cairo_surface_t *surface);
jpayne@68: Tells cairo that drawing has been done to surface using means other
jpayne@68: than cairo, and that cairo should reread any cached areas. Note
jpayne@68: that you must call cairo_surface_flush() before doing such drawing.
surface |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_surface_mark_dirty_rectangle (jpayne@68:cairo_surface_t *surface, jpayne@68:int x, jpayne@68:int y, jpayne@68:int width, jpayne@68:int height);
Like cairo_surface_mark_dirty(), but drawing has been done only to
jpayne@68: the specified rectangle, so that cairo can retain cached contents
jpayne@68: for other parts of the surface.
Any cached clip set on the surface will be reset by this function, jpayne@68: to make sure that future cairo calls have the clip set that they jpayne@68: expect.
jpayne@68:surface |
jpayne@68: jpayne@68: | jpayne@68: |
x |
jpayne@68: X coordinate of dirty rectangle |
jpayne@68: jpayne@68: |
y |
jpayne@68: Y coordinate of dirty rectangle |
jpayne@68: jpayne@68: |
width |
jpayne@68: width of dirty rectangle |
jpayne@68: jpayne@68: |
height |
jpayne@68: height of dirty rectangle |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_surface_set_device_offset (jpayne@68:cairo_surface_t *surface, jpayne@68:double x_offset, jpayne@68:double y_offset);
Sets an offset that is added to the device coordinates determined
jpayne@68: by the CTM when drawing to surface
jpayne@68: . One use case for this function
jpayne@68: is when we want to create a cairo_surface_t that redirects drawing
jpayne@68: for a portion of an onscreen surface to an offscreen surface in a
jpayne@68: way that is completely invisible to the user of the cairo
jpayne@68: API. Setting a transformation via cairo_translate() isn't
jpayne@68: sufficient to do this, since functions like
jpayne@68: cairo_device_to_user() will expose the hidden offset.
Note that the offset affects drawing to the surface as well as jpayne@68: using the surface in a source pattern.
jpayne@68:surface |
jpayne@68: jpayne@68: | jpayne@68: |
x_offset |
jpayne@68: the offset in the X direction, in device units |
jpayne@68: jpayne@68: |
y_offset |
jpayne@68: the offset in the Y direction, in device units |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_surface_get_device_offset (jpayne@68:cairo_surface_t *surface, jpayne@68:double *x_offset, jpayne@68:double *y_offset);
This function returns the previous device offset set by
jpayne@68: cairo_surface_set_device_offset().
surface |
jpayne@68: jpayne@68: | jpayne@68: |
x_offset |
jpayne@68: the offset in the X direction, in device units |
jpayne@68: jpayne@68: |
y_offset |
jpayne@68: the offset in the Y direction, in device units |
jpayne@68: jpayne@68: |
Since: 1.2
jpayne@68:void jpayne@68: cairo_surface_get_device_scale (jpayne@68:cairo_surface_t *surface, jpayne@68:double *x_scale, jpayne@68:double *y_scale);
This function returns the previous device offset set by
jpayne@68: cairo_surface_set_device_scale().
surface |
jpayne@68: jpayne@68: | jpayne@68: |
x_scale |
jpayne@68: the scale in the X direction, in device units |
jpayne@68: jpayne@68: |
y_scale |
jpayne@68: the scale in the Y direction, in device units |
jpayne@68: jpayne@68: |
Since: 1.14
jpayne@68:void jpayne@68: cairo_surface_set_device_scale (jpayne@68:cairo_surface_t *surface, jpayne@68:double x_scale, jpayne@68:double y_scale);
Sets a scale that is multiplied to the device coordinates determined
jpayne@68: by the CTM when drawing to surface
jpayne@68: . One common use for this is to
jpayne@68: render to very high resolution display devices at a scale factor, so
jpayne@68: that code that assumes 1 pixel will be a certain size will still work.
jpayne@68: Setting a transformation via cairo_translate() isn't
jpayne@68: sufficient to do this, since functions like
jpayne@68: cairo_device_to_user() will expose the hidden scale.
Note that the scale affects drawing to the surface as well as jpayne@68: using the surface in a source pattern.
jpayne@68:surface |
jpayne@68: jpayne@68: | jpayne@68: |
x_scale |
jpayne@68: a scale factor in the X direction |
jpayne@68: jpayne@68: |
y_scale |
jpayne@68: a scale factor in the Y direction |
jpayne@68: jpayne@68: |
Since: 1.14
jpayne@68:void jpayne@68: cairo_surface_set_fallback_resolution (jpayne@68:cairo_surface_t *surface, jpayne@68:double x_pixels_per_inch, jpayne@68:double y_pixels_per_inch);
Set the horizontal and vertical resolution for image fallbacks.
jpayne@68:When certain operations aren't supported natively by a backend, jpayne@68: cairo will fallback by rendering operations to an image and then jpayne@68: overlaying that image onto the output. For backends that are jpayne@68: natively vector-oriented, this function can be used to set the jpayne@68: resolution used for these image fallbacks, (larger values will jpayne@68: result in more detailed images, but also larger file sizes).
jpayne@68:Some examples of natively vector-oriented backends are the ps, pdf, jpayne@68: and svg backends.
jpayne@68:For backends that are natively raster-oriented, image fallbacks are jpayne@68: still possible, but they are always performed at the native jpayne@68: device resolution. So this function has no effect on those jpayne@68: backends.
jpayne@68:Note: The fallback resolution only takes effect at the time of
jpayne@68: completing a page (with cairo_show_page() or cairo_copy_page()) so
jpayne@68: there is currently no way to have more than one fallback resolution
jpayne@68: in effect on a single page.
The default fallback resoultion is 300 pixels per inch in both jpayne@68: dimensions.
jpayne@68:surface |
jpayne@68: jpayne@68: | jpayne@68: |
x_pixels_per_inch |
jpayne@68: horizontal setting for pixels per inch |
jpayne@68: jpayne@68: |
y_pixels_per_inch |
jpayne@68: vertical setting for pixels per inch |
jpayne@68: jpayne@68: |
Since: 1.2
jpayne@68:void jpayne@68: cairo_surface_get_fallback_resolution (jpayne@68:cairo_surface_t *surface, jpayne@68:double *x_pixels_per_inch, jpayne@68:double *y_pixels_per_inch);
This function returns the previous fallback resolution set by
jpayne@68: cairo_surface_set_fallback_resolution(), or default fallback
jpayne@68: resolution if never set.
surface |
jpayne@68: jpayne@68: | jpayne@68: |
x_pixels_per_inch |
jpayne@68: horizontal pixels per inch |
jpayne@68: jpayne@68: |
y_pixels_per_inch |
jpayne@68: vertical pixels per inch |
jpayne@68: jpayne@68: |
Since: 1.8
jpayne@68:cairo_surface_type_t
jpayne@68: cairo_surface_get_type (cairo_surface_t *surface);
jpayne@68: This function returns the type of the backend used to create jpayne@68: a surface. See cairo_surface_type_t for available types.
jpayne@68:surface |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.2
jpayne@68:unsigned int
jpayne@68: cairo_surface_get_reference_count (cairo_surface_t *surface);
jpayne@68: Returns the current reference count of surface
jpayne@68: .
surface |
jpayne@68: jpayne@68: | jpayne@68: |
the current reference count of surface
jpayne@68: . If the
jpayne@68: object is a nil object, 0 will be returned.
Since: 1.4
jpayne@68:cairo_status_t jpayne@68: cairo_surface_set_user_data (jpayne@68:cairo_surface_t *surface, jpayne@68:const cairo_user_data_key_t *key, jpayne@68:void *user_data, jpayne@68:cairo_destroy_func_t destroy);
Attach user data to surface
jpayne@68: . To remove user data from a surface,
jpayne@68: call this function with the key that was used to set it and NULL
jpayne@68: for data
jpayne@68: .
surface |
jpayne@68: jpayne@68: | jpayne@68: |
key |
jpayne@68: the address of a cairo_user_data_key_t to attach the user data to |
jpayne@68: jpayne@68: |
user_data |
jpayne@68: the user data to attach to the surface |
jpayne@68: jpayne@68: |
destroy |
jpayne@68: a cairo_destroy_func_t which will be called when the jpayne@68: surface is destroyed or when new user data is attached using the jpayne@68: same key. |
jpayne@68: jpayne@68: |
CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a
jpayne@68: slot could not be allocated for the user data.
Since: 1.0
jpayne@68:void * jpayne@68: cairo_surface_get_user_data (jpayne@68:cairo_surface_t *surface, jpayne@68:const cairo_user_data_key_t *key);
Return user data previously attached to surface
jpayne@68: using the specified
jpayne@68: key. If no user data has been attached with the given key this
jpayne@68: function returns NULL.
surface |
jpayne@68: jpayne@68: | jpayne@68: |
key |
jpayne@68: the address of the cairo_user_data_key_t the user data was jpayne@68: attached to |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void
jpayne@68: cairo_surface_copy_page (cairo_surface_t *surface);
jpayne@68: Emits the current page for backends that support multiple pages,
jpayne@68: but doesn't clear it, so that the contents of the current page will
jpayne@68: be retained for the next page. Use cairo_surface_show_page() if you
jpayne@68: want to get an empty page after the emission.
There is a convenience function for this that takes a cairo_t,
jpayne@68: namely cairo_copy_page().
surface |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.6
jpayne@68:void
jpayne@68: cairo_surface_show_page (cairo_surface_t *surface);
jpayne@68: Emits and clears the current page for backends that support multiple
jpayne@68: pages. Use cairo_surface_copy_page() if you don't want to clear the page.
There is a convenience function for this that takes a cairo_t,
jpayne@68: namely cairo_show_page().
surface |
jpayne@68: a cairo_Surface_t |
jpayne@68: jpayne@68: |
Since: 1.6
jpayne@68:cairo_bool_t
jpayne@68: cairo_surface_has_show_text_glyphs (cairo_surface_t *surface);
jpayne@68: Returns whether the surface supports
jpayne@68: sophisticated cairo_show_text_glyphs() operations. That is,
jpayne@68: whether it actually uses the provided text and cluster data
jpayne@68: to a cairo_show_text_glyphs() call.
Note: Even if this function returns FALSE, a
jpayne@68: cairo_show_text_glyphs() operation targeted at surface
jpayne@68: will
jpayne@68: still succeed. It just will
jpayne@68: act like a cairo_show_glyphs() operation. Users can use this
jpayne@68: function to avoid computing UTF-8 text and cluster mapping if the
jpayne@68: target surface does not use it.
surface |
jpayne@68: jpayne@68: | jpayne@68: |
TRUE if surface
jpayne@68: supports
jpayne@68: cairo_show_text_glyphs(), FALSE otherwise
Since: 1.8
jpayne@68:cairo_status_t jpayne@68: cairo_surface_set_mime_data (jpayne@68:cairo_surface_t *surface, jpayne@68:const char *mime_type, jpayne@68:const unsigned char *data, jpayne@68:unsigned long length, jpayne@68:cairo_destroy_func_t destroy, jpayne@68:void *closure);
Attach an image in the format mime_type
jpayne@68: to surface
jpayne@68: . To remove
jpayne@68: the data from a surface, call this function with same mime type
jpayne@68: and NULL for data
jpayne@68: .
The attached image (or filename) data can later be used by backends
jpayne@68: which support it (currently: PDF, PS, SVG and Win32 Printing
jpayne@68: surfaces) to emit this data instead of making a snapshot of the
jpayne@68: surface
jpayne@68: . This approach tends to be faster and requires less
jpayne@68: memory and disk space.
The recognized MIME types are the following: CAIRO_MIME_TYPE_JPEG,
jpayne@68: CAIRO_MIME_TYPE_PNG, CAIRO_MIME_TYPE_JP2, CAIRO_MIME_TYPE_URI,
jpayne@68: CAIRO_MIME_TYPE_UNIQUE_ID, CAIRO_MIME_TYPE_JBIG2,
jpayne@68: CAIRO_MIME_TYPE_JBIG2_GLOBAL, CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID,
jpayne@68: CAIRO_MIME_TYPE_CCITT_FAX, CAIRO_MIME_TYPE_CCITT_FAX_PARAMS.
See corresponding backend surface docs for details about which MIME jpayne@68: types it can handle. Caution: the associated MIME data will be jpayne@68: discarded if you draw on the surface afterwards. Use this function jpayne@68: with care.
jpayne@68:Even if a backend supports a MIME type, that does not mean cairo jpayne@68: will always be able to use the attached MIME data. For example, if jpayne@68: the backend does not natively support the compositing operation used jpayne@68: to apply the MIME data to the backend. In that case, the MIME data jpayne@68: will be ignored. Therefore, to apply an image in all cases, it is best jpayne@68: to create an image surface which contains the decoded image data and jpayne@68: then attach the MIME data to that. This ensures the image will always jpayne@68: be used while still allowing the MIME data to be used whenever jpayne@68: possible.
jpayne@68:surface |
jpayne@68: jpayne@68: | jpayne@68: |
mime_type |
jpayne@68: the MIME type of the image data |
jpayne@68: jpayne@68: |
data |
jpayne@68: the image data to attach to the surface |
jpayne@68: jpayne@68: |
length |
jpayne@68: the length of the image data |
jpayne@68: jpayne@68: |
destroy |
jpayne@68: a cairo_destroy_func_t which will be called when the jpayne@68: surface is destroyed or when new image data is attached using the jpayne@68: same mime type. |
jpayne@68: jpayne@68: |
closure |
jpayne@68: the data to be passed to the |
jpayne@68: jpayne@68: |
CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a
jpayne@68: slot could not be allocated for the user data.
Since: 1.10
jpayne@68:void jpayne@68: cairo_surface_get_mime_data (jpayne@68:cairo_surface_t *surface, jpayne@68:const char *mime_type, jpayne@68:const unsigned char **data, jpayne@68:unsigned long *length);
Return mime data previously attached to surface
jpayne@68: using the
jpayne@68: specified mime type. If no data has been attached with the given
jpayne@68: mime type, data
jpayne@68: is set NULL.
surface |
jpayne@68: jpayne@68: | jpayne@68: |
mime_type |
jpayne@68: the mime type of the image data |
jpayne@68: jpayne@68: |
data |
jpayne@68: the image data to attached to the surface |
jpayne@68: jpayne@68: |
length |
jpayne@68: the length of the image data |
jpayne@68: jpayne@68: |
Since: 1.10
jpayne@68:cairo_bool_t jpayne@68: cairo_surface_supports_mime_type (jpayne@68:cairo_surface_t *surface, jpayne@68:const char *mime_type);
Return whether surface
jpayne@68: supports mime_type
jpayne@68: .
surface |
jpayne@68: jpayne@68: | jpayne@68: |
mime_type |
jpayne@68: the mime type |
jpayne@68: jpayne@68: |
TRUE if surface
jpayne@68: supports
jpayne@68: mime_type
jpayne@68: , FALSE otherwise
Since: 1.12
jpayne@68:cairo_surface_t * jpayne@68: cairo_surface_map_to_image (jpayne@68:cairo_surface_t *surface, jpayne@68:const cairo_rectangle_int_t *extents);
Returns an image surface that is the most efficient mechanism for
jpayne@68: modifying the backing store of the target surface. The region retrieved
jpayne@68: may be limited to the extents
jpayne@68: or NULL for the whole surface
Note, the use of the original surface as a target or source whilst
jpayne@68: it is mapped is undefined. The result of mapping the surface
jpayne@68: multiple times is undefined. Calling cairo_surface_destroy() or
jpayne@68: cairo_surface_finish() on the resulting image surface results in
jpayne@68: undefined behavior. Changing the device transform of the image
jpayne@68: surface or of surface
jpayne@68: before the image surface is unmapped results
jpayne@68: in undefined behavior.
surface |
jpayne@68: an existing surface used to extract the image from |
jpayne@68: jpayne@68: |
extents |
jpayne@68: limit the extraction to an rectangular region |
jpayne@68: jpayne@68: |
a pointer to the newly allocated image surface. The caller
jpayne@68: must use cairo_surface_unmap_image() to destroy this image surface.
This function always returns a valid pointer, but it will return a
jpayne@68: pointer to a "nil" surface if other
jpayne@68: is already in an error state
jpayne@68: or any other error occurs. If the returned pointer does not have an
jpayne@68: error status, it is guaranteed to be an image surface whose format
jpayne@68: is not CAIRO_FORMAT_INVALID.
Since: 1.12
jpayne@68:void jpayne@68: cairo_surface_unmap_image (jpayne@68:cairo_surface_t *surface, jpayne@68:cairo_surface_t *image);
Unmaps the image surface as returned from cairo_surface_map_to_image().
The content of the image will be uploaded to the target surface. jpayne@68: Afterwards, the image is destroyed.
jpayne@68:Using an image surface which wasn't returned by cairo_surface_map_to_image()
jpayne@68: results in undefined behavior.
surface |
jpayne@68: the surface passed to |
jpayne@68: jpayne@68: |
image |
jpayne@68: the currently mapped image |
jpayne@68: jpayne@68: |
Since: 1.12
jpayne@68:#define CAIRO_MIME_TYPE_CCITT_FAX "image/g3fax" jpayne@68:jpayne@68:
Group 3 or Group 4 CCITT facsimile encoding (International jpayne@68: Telecommunication Union, Recommendations T.4 and T.6.)
jpayne@68:Since: 1.16
jpayne@68:#define CAIRO_MIME_TYPE_CCITT_FAX_PARAMS "application/x-cairo.ccitt.params" jpayne@68:jpayne@68:
Decode parameters for Group 3 or Group 4 CCITT facsimile encoding. jpayne@68: See CCITT Fax Images.
jpayne@68:Since: 1.16
jpayne@68:#define CAIRO_MIME_TYPE_EPS "application/postscript" jpayne@68:jpayne@68:
Encapsulated PostScript file. jpayne@68: Encapsulated PostScript File Format Specification
jpayne@68:Since: 1.16
jpayne@68:#define CAIRO_MIME_TYPE_EPS_PARAMS "application/x-cairo.eps.params" jpayne@68:jpayne@68:
Embedding parameters Encapsulated PostScript data. jpayne@68: See Embedding EPS files.
jpayne@68:Since: 1.16
jpayne@68:#define CAIRO_MIME_TYPE_JBIG2 "application/x-cairo.jbig2" jpayne@68:jpayne@68:
Joint Bi-level Image Experts Group image coding standard (ISO/IEC 11544).
jpayne@68:Since: 1.14
jpayne@68:#define CAIRO_MIME_TYPE_JBIG2_GLOBAL "application/x-cairo.jbig2-global" jpayne@68:jpayne@68:
Joint Bi-level Image Experts Group image coding standard (ISO/IEC 11544) global segment.
jpayne@68:Since: 1.14
jpayne@68:#define CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID "application/x-cairo.jbig2-global-id" jpayne@68:jpayne@68:
An unique identifier shared by a JBIG2 global segment and all JBIG2 images jpayne@68: that depend on the global segment.
jpayne@68:Since: 1.14
jpayne@68:#define CAIRO_MIME_TYPE_JP2 "image/jp2" jpayne@68:jpayne@68:
The Joint Photographic Experts Group (JPEG) 2000 image coding standard (ISO/IEC 15444-1).
jpayne@68:Since: 1.10
jpayne@68:#define CAIRO_MIME_TYPE_JPEG "image/jpeg" jpayne@68:jpayne@68:
The Joint Photographic Experts Group (JPEG) image coding standard (ISO/IEC 10918-1).
jpayne@68:Since: 1.10
jpayne@68:#define CAIRO_MIME_TYPE_PNG "image/png" jpayne@68:jpayne@68:
The Portable Network Graphics image file format (ISO/IEC 15948).
jpayne@68:Since: 1.10
jpayne@68:#define CAIRO_MIME_TYPE_URI "text/x-uri" jpayne@68:jpayne@68:
URI for an image file (unofficial MIME type).
jpayne@68:Since: 1.10
jpayne@68:#define CAIRO_MIME_TYPE_UNIQUE_ID "application/x-cairo.uuid" jpayne@68:jpayne@68:
Unique identifier for a surface (cairo specific MIME type). All surfaces with jpayne@68: the same unique identifier will only be embedded once.
jpayne@68:Since: 1.12
jpayne@68:typedef struct _cairo_surface cairo_surface_t; jpayne@68:jpayne@68:
A cairo_surface_t represents an image, either as the destination
jpayne@68: of a drawing operation or as source when drawing onto another
jpayne@68: surface. To draw to a cairo_surface_t, create a cairo context
jpayne@68: with the surface as the target, using cairo_create().
There are different subtypes of cairo_surface_t for
jpayne@68: different drawing backends; for example, cairo_image_surface_create()
jpayne@68: creates a bitmap image in memory.
jpayne@68: The type of a surface can be queried with cairo_surface_get_type().
The initial contents of a surface after creation depend upon the manner
jpayne@68: of its creation. If cairo creates the surface and backing storage for
jpayne@68: the user, it will be initially cleared; for example,
jpayne@68: cairo_image_surface_create() and cairo_surface_create_similar().
jpayne@68: Alternatively, if the user passes in a reference to some backing storage
jpayne@68: and asks cairo to wrap that in a cairo_surface_t, then the contents are
jpayne@68: not modified; for example, cairo_image_surface_create_for_data() and
jpayne@68: cairo_xlib_surface_create().
Memory management of cairo_surface_t is done with
jpayne@68: cairo_surface_reference() and cairo_surface_destroy().
Since: 1.0
jpayne@68:cairo_content_t is used to describe the content that a surface will jpayne@68: contain, whether color information, alpha information (translucence jpayne@68: vs. opacity), or both.
jpayne@68:Note: The large values here are designed to keep cairo_content_t jpayne@68: values distinct from cairo_format_t values so that the jpayne@68: implementation can detect the error if users confuse the two types.
jpayne@68:| jpayne@68: |
jpayne@68: The surface will hold color content only. (Since 1.0) jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface will hold alpha content only. (Since 1.0) jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface will hold color and alpha content. (Since 1.0) jpayne@68: |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:cairo_surface_type_t is used to describe the type of a given jpayne@68: surface. The surface types are also known as "backends" or "surface jpayne@68: backends" within cairo.
jpayne@68:The type of a surface is determined by the function used to create
jpayne@68: it, which will generally be of the form
jpayne@68: cairo_type_surface_create(),
jpayne@68: (though see cairo_surface_create_similar() as well).
The surface type can be queried with cairo_surface_get_type()
The various cairo_surface_t functions can be used with surfaces of
jpayne@68: any type, but some backends also provide type-specific functions
jpayne@68: that must only be called with a surface of the appropriate
jpayne@68: type. These functions have names that begin with
jpayne@68: cairo_type_surface such as cairo_image_surface_get_width().
The behavior of calling a type-specific function with a surface of jpayne@68: the wrong type is undefined.
jpayne@68:New entries may be added in future versions.
jpayne@68:| jpayne@68: |
jpayne@68: The surface is of type image, since 1.2 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type pdf, since 1.2 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type ps, since 1.2 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type xlib, since 1.2 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type xcb, since 1.2 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type glitz, since 1.2 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type quartz, since 1.2 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type win32, since 1.2 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type beos, since 1.2 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type directfb, since 1.2 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type svg, since 1.2 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type os2, since 1.4 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is a win32 printing surface, since 1.6 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type quartz_image, since 1.6 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type script, since 1.10 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type Qt, since 1.10 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type recording, since 1.10 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is a OpenVG surface, since 1.10 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type OpenGL, since 1.10 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type Direct Render Manager, since 1.10 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type 'tee' (a multiplexing surface), since 1.10 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is of type XML (for debugging), since 1.10 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: | jpayne@68: | jpayne@68: |
| jpayne@68: |
jpayne@68: The surface is a subsurface created with
jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: This surface is of type Cogl, since 1.12 jpayne@68: |
jpayne@68: jpayne@68: |
Since: 1.2
jpayne@68: