jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: Raster Sources: Cairo: A Vector Graphics Library jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68: jpayne@68: jpayne@68:
jpayne@68:

Raster Sources

jpayne@68:

Raster Sources — Supplying arbitrary image data

jpayne@68:
jpayne@68:
jpayne@68:

Functions

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:
jpayne@68: cairo_pattern_t * jpayne@68: jpayne@68: cairo_pattern_create_raster_source () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_raster_source_pattern_set_callback_data () jpayne@68:
jpayne@68: void * jpayne@68: jpayne@68: cairo_raster_source_pattern_get_callback_data () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_raster_source_pattern_set_acquire () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_raster_source_pattern_get_acquire () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_raster_source_pattern_set_snapshot () jpayne@68:
jpayne@68: cairo_raster_source_snapshot_func_t jpayne@68: jpayne@68: cairo_raster_source_pattern_get_snapshot () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_raster_source_pattern_set_copy () jpayne@68:
jpayne@68: cairo_raster_source_copy_func_t jpayne@68: jpayne@68: cairo_raster_source_pattern_get_copy () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_raster_source_pattern_set_finish () jpayne@68:
jpayne@68: cairo_raster_source_finish_func_t jpayne@68: jpayne@68: cairo_raster_source_pattern_get_finish () jpayne@68:
jpayne@68: cairo_surface_t jpayne@68: jpayne@68: (*cairo_raster_source_acquire_func_t) () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: (*cairo_raster_source_release_func_t) () jpayne@68:
jpayne@68: cairo_status_t jpayne@68: jpayne@68: (*cairo_raster_source_snapshot_func_t) () jpayne@68:
jpayne@68: cairo_status_t jpayne@68: jpayne@68: (*cairo_raster_source_copy_func_t) () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: (*cairo_raster_source_finish_func_t) () jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

Description

jpayne@68:

The raster source provides the ability to supply arbitrary pixel data jpayne@68: whilst rendering. The pixels are queried at the time of rasterisation jpayne@68: by means of user callback functions, allowing for the ultimate jpayne@68: flexibility. For example, in handling compressed image sources, you jpayne@68: may keep a MRU cache of decompressed images and decompress sources on the jpayne@68: fly and discard old ones to conserve memory.

jpayne@68:

For the raster source to be effective, you must at least specify jpayne@68: the acquire and release callbacks which are used to retrieve the pixel jpayne@68: data for the region of interest and demark when it can be freed afterwards. jpayne@68: Other callbacks are provided for when the pattern is copied temporarily jpayne@68: during rasterisation, or more permanently as a snapshot in order to keep jpayne@68: the pixel data available for printing.

jpayne@68:
jpayne@68:
jpayne@68:

Functions

jpayne@68:
jpayne@68:

cairo_pattern_create_raster_source ()

jpayne@68: 
cairo_pattern_t *
jpayne@68: cairo_pattern_create_raster_source (void *user_data,
jpayne@68:                                     cairo_content_t content,
jpayne@68:                                     int width,
jpayne@68:                                     int height);
jpayne@68:

Creates a new user pattern for providing pixel data.

jpayne@68:

Use the setter functions to associate callbacks with the returned jpayne@68: pattern. The only mandatory callback is acquire.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

user_data

the user data to be passed to all callbacks

 

content

content type for the pixel data that will be returned. Knowing jpayne@68: the content type ahead of time is used for analysing the operation and jpayne@68: picking the appropriate rendering path.

 

width

maximum size of the sample area

 

height

maximum size of the sample area

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

a newly created cairo_pattern_t. Free with jpayne@68: cairo_pattern_destroy() when you are done using it.

jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_pattern_set_callback_data ()

jpayne@68: 
void
jpayne@68: cairo_raster_source_pattern_set_callback_data
jpayne@68:                                (cairo_pattern_t *pattern,
jpayne@68:                                 void *data);
jpayne@68:

Updates the user data that is provided to all callbacks.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the pattern to update

 

data

the user data to be passed to all callbacks

 
jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_pattern_get_callback_data ()

jpayne@68: 
void *
jpayne@68: cairo_raster_source_pattern_get_callback_data
jpayne@68:                                (cairo_pattern_t *pattern);
jpayne@68:

Queries the current user data.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the pattern to update

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

the current user-data passed to each callback

jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_pattern_set_acquire ()

jpayne@68: 
void
jpayne@68: cairo_raster_source_pattern_set_acquire
jpayne@68:                                (cairo_pattern_t *pattern,
jpayne@68:                                 cairo_raster_source_acquire_func_t acquire,
jpayne@68:                                 cairo_raster_source_release_func_t release);
jpayne@68:

Specifies the callbacks used to generate the image surface for a rendering jpayne@68: operation (acquire) and the function used to cleanup that surface afterwards.

jpayne@68:

The acquire jpayne@68: callback should create a surface (preferably an image jpayne@68: surface created to match the target using jpayne@68: cairo_surface_create_similar_image()) that defines at least the region jpayne@68: of interest specified by extents. The surface is allowed to be the entire jpayne@68: sample area, but if it does contain a subsection of the sample area, jpayne@68: the surface extents should be provided by setting the device offset (along jpayne@68: with its width and height) using cairo_surface_set_device_offset().

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the pattern to update

 

acquire

acquire callback

 

release

release callback

 
jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_pattern_get_acquire ()

jpayne@68: 
void
jpayne@68: cairo_raster_source_pattern_get_acquire
jpayne@68:                                (cairo_pattern_t *pattern,
jpayne@68:                                 cairo_raster_source_acquire_func_t *acquire,
jpayne@68:                                 cairo_raster_source_release_func_t *release);
jpayne@68:

Queries the current acquire and release callbacks.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the pattern to query

 

acquire

return value for the current acquire callback

 

release

return value for the current release callback

 
jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_pattern_set_snapshot ()

jpayne@68: 
void
jpayne@68: cairo_raster_source_pattern_set_snapshot
jpayne@68:                                (cairo_pattern_t *pattern,
jpayne@68:                                 cairo_raster_source_snapshot_func_t snapshot);
jpayne@68:

Sets the callback that will be used whenever a snapshot is taken of the jpayne@68: pattern, that is whenever the current contents of the pattern should be jpayne@68: preserved for later use. This is typically invoked whilst printing.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the pattern to update

 

snapshot

snapshot callback

 
jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_pattern_get_snapshot ()

jpayne@68: 
cairo_raster_source_snapshot_func_t
jpayne@68: cairo_raster_source_pattern_get_snapshot
jpayne@68:                                (cairo_pattern_t *pattern);
jpayne@68:

Queries the current snapshot callback.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the pattern to query

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

the current snapshot callback

jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_pattern_set_copy ()

jpayne@68: 
void
jpayne@68: cairo_raster_source_pattern_set_copy (cairo_pattern_t *pattern,
jpayne@68:                                       cairo_raster_source_copy_func_t copy);
jpayne@68:

Updates the copy callback which is used whenever a temporary copy of the jpayne@68: pattern is taken.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the pattern to update

 

copy

the copy callback

 
jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_pattern_get_copy ()

jpayne@68: 
cairo_raster_source_copy_func_t
jpayne@68: cairo_raster_source_pattern_get_copy (cairo_pattern_t *pattern);
jpayne@68:

Queries the current copy callback.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the pattern to query

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

the current copy callback

jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_pattern_set_finish ()

jpayne@68: 
void
jpayne@68: cairo_raster_source_pattern_set_finish
jpayne@68:                                (cairo_pattern_t *pattern,
jpayne@68:                                 cairo_raster_source_finish_func_t finish);
jpayne@68:

Updates the finish callback which is used whenever a pattern (or a copy jpayne@68: thereof) will no longer be used.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the pattern to update

 

finish

the finish callback

 
jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_pattern_get_finish ()

jpayne@68: 
cairo_raster_source_finish_func_t
jpayne@68: cairo_raster_source_pattern_get_finish
jpayne@68:                                (cairo_pattern_t *pattern);
jpayne@68:

Queries the current finish callback.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the pattern to query

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

the current finish callback

jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_acquire_func_t ()

jpayne@68: 
cairo_surface_t
jpayne@68: (*cairo_raster_source_acquire_func_t) (cairo_pattern_t *pattern,
jpayne@68:                                        void *callback_data,
jpayne@68:                                        cairo_surface_t *target,
jpayne@68:                                        const cairo_rectangle_int_t *extents);
jpayne@68:

cairo_raster_source_acquire_func_t is the type of function which is jpayne@68: called when a pattern is being rendered from. It should create a surface jpayne@68: that provides the pixel data for the region of interest as defined by jpayne@68: extents, though the surface itself does not have to be limited to that jpayne@68: area. For convenience the surface should probably be of image type, jpayne@68: created with cairo_surface_create_similar_image() for the target (which jpayne@68: enables the number of copies to be reduced during transfer to the jpayne@68: device). Another option, might be to return a similar surface to the jpayne@68: target for explicit handling by the application of a set of cached sources jpayne@68: on the device. The region of sample data provided should be defined using jpayne@68: cairo_surface_set_device_offset() to specify the top-left corner of the jpayne@68: sample data (along with width and height of the surface).

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the pattern being rendered from

 

callback_data

the user data supplied during creation

 

target

the rendering target surface

 

extents

rectangular region of interest in pixels in sample space

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

a cairo_surface_t

jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_release_func_t ()

jpayne@68: 
void
jpayne@68: (*cairo_raster_source_release_func_t) (cairo_pattern_t *pattern,
jpayne@68:                                        void *callback_data,
jpayne@68:                                        cairo_surface_t *surface);
jpayne@68:

cairo_raster_source_release_func_t is the type of function which is jpayne@68: called when the pixel data is no longer being access by the pattern jpayne@68: for the rendering operation. Typically this function will simply jpayne@68: destroy the surface created during acquire.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the pattern being rendered from

 

callback_data

the user data supplied during creation

 

surface

the surface created during acquire

 
jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_snapshot_func_t ()

jpayne@68: 
cairo_status_t
jpayne@68: (*cairo_raster_source_snapshot_func_t)
jpayne@68:                                (cairo_pattern_t *pattern,
jpayne@68:                                 void *callback_data);
jpayne@68:

cairo_raster_source_snapshot_func_t is the type of function which is jpayne@68: called when the pixel data needs to be preserved for later use jpayne@68: during printing. This pattern will be accessed again later, and it jpayne@68: is expected to provide the pixel data that was current at the time jpayne@68: of snapshotting.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the pattern being rendered from

 

callback_data

the user data supplied during creation

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

CAIRO_STATUS_SUCCESS on success, or one of the jpayne@68: cairo_status_t error codes for failure.

jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_copy_func_t ()

jpayne@68: 
cairo_status_t
jpayne@68: (*cairo_raster_source_copy_func_t) (cairo_pattern_t *pattern,
jpayne@68:                                     void *callback_data,
jpayne@68:                                     const cairo_pattern_t *other);
jpayne@68:

cairo_raster_source_copy_func_t is the type of function which is jpayne@68: called when the pattern gets copied as a normal part of rendering.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the cairo_pattern_t that was copied to

 

callback_data

the user data supplied during creation

 

other

the cairo_pattern_t being used as the source for the copy

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

CAIRO_STATUS_SUCCESS on success, or one of the jpayne@68: cairo_status_t error codes for failure.

jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_raster_source_finish_func_t ()

jpayne@68: 
void
jpayne@68: (*cairo_raster_source_finish_func_t) (cairo_pattern_t *pattern,
jpayne@68:                                       void *callback_data);
jpayne@68:

cairo_raster_source_finish_func_t is the type of function which is jpayne@68: called when the pattern (or a copy thereof) is no longer required.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

pattern

the pattern being rendered from

 

callback_data

the user data supplied during creation

 
jpayne@68:
jpayne@68:

Since: 1.12

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

Types and Values

jpayne@68:
jpayne@68:
jpayne@68:

See Also

jpayne@68:

cairo_pattern_t

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:
Generated by GTK-Doc V1.27
jpayne@68: jpayne@68: