From 530ffd0b7d3c39757b20f00716e486b5caf89aff Mon Sep 17 00:00:00 2001 From: sanine Date: Wed, 12 Oct 2022 12:03:23 -0500 Subject: add cairo --- .../doc/public/xml/cairo-raster-source.xml | 550 +++++++++++++++++++++ 1 file changed, 550 insertions(+) create mode 100644 libs/cairo-1.16.0/doc/public/xml/cairo-raster-source.xml (limited to 'libs/cairo-1.16.0/doc/public/xml/cairo-raster-source.xml') diff --git a/libs/cairo-1.16.0/doc/public/xml/cairo-raster-source.xml b/libs/cairo-1.16.0/doc/public/xml/cairo-raster-source.xml new file mode 100644 index 0000000..227bb18 --- /dev/null +++ b/libs/cairo-1.16.0/doc/public/xml/cairo-raster-source.xml @@ -0,0 +1,550 @@ + + +]> + + +Raster Sources +3 +CAIRO Library + + +Raster Sources +Supplying arbitrary image data + + + +Functions + + + + + +cairo_pattern_t * +cairo_pattern_create_raster_source () +void +cairo_raster_source_pattern_set_callback_data () +void * +cairo_raster_source_pattern_get_callback_data () +void +cairo_raster_source_pattern_set_acquire () +void +cairo_raster_source_pattern_get_acquire () +void +cairo_raster_source_pattern_set_snapshot () +cairo_raster_source_snapshot_func_t +cairo_raster_source_pattern_get_snapshot () +void +cairo_raster_source_pattern_set_copy () +cairo_raster_source_copy_func_t +cairo_raster_source_pattern_get_copy () +void +cairo_raster_source_pattern_set_finish () +cairo_raster_source_finish_func_t +cairo_raster_source_pattern_get_finish () +cairo_surface_t +(*cairo_raster_source_acquire_func_t) () +void +(*cairo_raster_source_release_func_t) () +cairo_status_t +(*cairo_raster_source_snapshot_func_t) () +cairo_status_t +(*cairo_raster_source_copy_func_t) () +void +(*cairo_raster_source_finish_func_t) () + + + + + + + + +Description +The raster source provides the ability to supply arbitrary pixel data +whilst rendering. The pixels are queried at the time of rasterisation +by means of user callback functions, allowing for the ultimate +flexibility. For example, in handling compressed image sources, you +may keep a MRU cache of decompressed images and decompress sources on the +fly and discard old ones to conserve memory. +For the raster source to be effective, you must at least specify +the acquire and release callbacks which are used to retrieve the pixel +data for the region of interest and demark when it can be freed afterwards. +Other callbacks are provided for when the pattern is copied temporarily +during rasterisation, or more permanently as a snapshot in order to keep +the pixel data available for printing. + + + +Functions + +cairo_pattern_create_raster_source () +cairo_pattern_create_raster_source +cairo_pattern_t * +cairo_pattern_create_raster_source (void *user_data, + cairo_content_t content, + int width, + int height); +Creates a new user pattern for providing pixel data. +Use the setter functions to associate callbacks with the returned +pattern. The only mandatory callback is acquire. + +Parameters + + + + + + +user_data +the user data to be passed to all callbacks + +content +content type for the pixel data that will be returned. Knowing +the content type ahead of time is used for analysing the operation and +picking the appropriate rendering path. + +width +maximum size of the sample area + +height +maximum size of the sample area + + + +Returns + a newly created cairo_pattern_t. Free with +cairo_pattern_destroy() when you are done using it. +Since: 1.12 + +cairo_raster_source_pattern_set_callback_data () +cairo_raster_source_pattern_set_callback_data +void +cairo_raster_source_pattern_set_callback_data + (cairo_pattern_t *pattern, + void *data); +Updates the user data that is provided to all callbacks. + +Parameters + + + + + + +pattern +the pattern to update + +data +the user data to be passed to all callbacks + + +Since: 1.12 + +cairo_raster_source_pattern_get_callback_data () +cairo_raster_source_pattern_get_callback_data +void * +cairo_raster_source_pattern_get_callback_data + (cairo_pattern_t *pattern); +Queries the current user data. + +Parameters + + + + + + +pattern +the pattern to update + + + +Returns + the current user-data passed to each callback +Since: 1.12 + +cairo_raster_source_pattern_set_acquire () +cairo_raster_source_pattern_set_acquire +void +cairo_raster_source_pattern_set_acquire + (cairo_pattern_t *pattern, + cairo_raster_source_acquire_func_t acquire, + cairo_raster_source_release_func_t release); +Specifies the callbacks used to generate the image surface for a rendering +operation (acquire) and the function used to cleanup that surface afterwards. +The acquire + callback should create a surface (preferably an image +surface created to match the target using +cairo_surface_create_similar_image()) that defines at least the region +of interest specified by extents. The surface is allowed to be the entire +sample area, but if it does contain a subsection of the sample area, +the surface extents should be provided by setting the device offset (along +with its width and height) using cairo_surface_set_device_offset(). + +Parameters + + + + + + +pattern +the pattern to update + +acquire +acquire callback + +release +release callback + + +Since: 1.12 + +cairo_raster_source_pattern_get_acquire () +cairo_raster_source_pattern_get_acquire +void +cairo_raster_source_pattern_get_acquire + (cairo_pattern_t *pattern, + cairo_raster_source_acquire_func_t *acquire, + cairo_raster_source_release_func_t *release); +Queries the current acquire and release callbacks. + +Parameters + + + + + + +pattern +the pattern to query + +acquire +return value for the current acquire callback + +release +return value for the current release callback + + +Since: 1.12 + +cairo_raster_source_pattern_set_snapshot () +cairo_raster_source_pattern_set_snapshot +void +cairo_raster_source_pattern_set_snapshot + (cairo_pattern_t *pattern, + cairo_raster_source_snapshot_func_t snapshot); +Sets the callback that will be used whenever a snapshot is taken of the +pattern, that is whenever the current contents of the pattern should be +preserved for later use. This is typically invoked whilst printing. + +Parameters + + + + + + +pattern +the pattern to update + +snapshot +snapshot callback + + +Since: 1.12 + +cairo_raster_source_pattern_get_snapshot () +cairo_raster_source_pattern_get_snapshot +cairo_raster_source_snapshot_func_t +cairo_raster_source_pattern_get_snapshot + (cairo_pattern_t *pattern); +Queries the current snapshot callback. + +Parameters + + + + + + +pattern +the pattern to query + + + +Returns + the current snapshot callback +Since: 1.12 + +cairo_raster_source_pattern_set_copy () +cairo_raster_source_pattern_set_copy +void +cairo_raster_source_pattern_set_copy (cairo_pattern_t *pattern, + cairo_raster_source_copy_func_t copy); +Updates the copy callback which is used whenever a temporary copy of the +pattern is taken. + +Parameters + + + + + + +pattern +the pattern to update + +copy +the copy callback + + +Since: 1.12 + +cairo_raster_source_pattern_get_copy () +cairo_raster_source_pattern_get_copy +cairo_raster_source_copy_func_t +cairo_raster_source_pattern_get_copy (cairo_pattern_t *pattern); +Queries the current copy callback. + +Parameters + + + + + + +pattern +the pattern to query + + + +Returns + the current copy callback +Since: 1.12 + +cairo_raster_source_pattern_set_finish () +cairo_raster_source_pattern_set_finish +void +cairo_raster_source_pattern_set_finish + (cairo_pattern_t *pattern, + cairo_raster_source_finish_func_t finish); +Updates the finish callback which is used whenever a pattern (or a copy +thereof) will no longer be used. + +Parameters + + + + + + +pattern +the pattern to update + +finish +the finish callback + + +Since: 1.12 + +cairo_raster_source_pattern_get_finish () +cairo_raster_source_pattern_get_finish +cairo_raster_source_finish_func_t +cairo_raster_source_pattern_get_finish + (cairo_pattern_t *pattern); +Queries the current finish callback. + +Parameters + + + + + + +pattern +the pattern to query + + + +Returns + the current finish callback +Since: 1.12 + +cairo_raster_source_acquire_func_t () +cairo_raster_source_acquire_func_t +cairo_surface_t +(*cairo_raster_source_acquire_func_t) (cairo_pattern_t *pattern, + void *callback_data, + cairo_surface_t *target, + const cairo_rectangle_int_t *extents); +cairo_raster_source_acquire_func_t is the type of function which is +called when a pattern is being rendered from. It should create a surface +that provides the pixel data for the region of interest as defined by +extents, though the surface itself does not have to be limited to that +area. For convenience the surface should probably be of image type, +created with cairo_surface_create_similar_image() for the target (which +enables the number of copies to be reduced during transfer to the +device). Another option, might be to return a similar surface to the +target for explicit handling by the application of a set of cached sources +on the device. The region of sample data provided should be defined using +cairo_surface_set_device_offset() to specify the top-left corner of the +sample data (along with width and height of the surface). + +Parameters + + + + + + +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 + + + +Returns + a cairo_surface_t +Since: 1.12 + +cairo_raster_source_release_func_t () +cairo_raster_source_release_func_t +void +(*cairo_raster_source_release_func_t) (cairo_pattern_t *pattern, + void *callback_data, + cairo_surface_t *surface); +cairo_raster_source_release_func_t is the type of function which is +called when the pixel data is no longer being access by the pattern +for the rendering operation. Typically this function will simply +destroy the surface created during acquire. + +Parameters + + + + + + +pattern +the pattern being rendered from + +callback_data +the user data supplied during creation + +surface +the surface created during acquire + + +Since: 1.12 + +cairo_raster_source_snapshot_func_t () +cairo_raster_source_snapshot_func_t +cairo_status_t +(*cairo_raster_source_snapshot_func_t) + (cairo_pattern_t *pattern, + void *callback_data); +cairo_raster_source_snapshot_func_t is the type of function which is +called when the pixel data needs to be preserved for later use +during printing. This pattern will be accessed again later, and it +is expected to provide the pixel data that was current at the time +of snapshotting. + +Parameters + + + + + + +pattern +the pattern being rendered from + +callback_data +the user data supplied during creation + + + +Returns + CAIRO_STATUS_SUCCESS on success, or one of the +cairo_status_t error codes for failure. +Since: 1.12 + +cairo_raster_source_copy_func_t () +cairo_raster_source_copy_func_t +cairo_status_t +(*cairo_raster_source_copy_func_t) (cairo_pattern_t *pattern, + void *callback_data, + const cairo_pattern_t *other); +cairo_raster_source_copy_func_t is the type of function which is +called when the pattern gets copied as a normal part of rendering. + +Parameters + + + + + + +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 + + + +Returns + CAIRO_STATUS_SUCCESS on success, or one of the +cairo_status_t error codes for failure. +Since: 1.12 + +cairo_raster_source_finish_func_t () +cairo_raster_source_finish_func_t +void +(*cairo_raster_source_finish_func_t) (cairo_pattern_t *pattern, + void *callback_data); +cairo_raster_source_finish_func_t is the type of function which is +called when the pattern (or a copy thereof) is no longer required. + +Parameters + + + + + + +pattern +the pattern being rendered from + +callback_data +the user data supplied during creation + + +Since: 1.12 + + + +Types and Values + + + +See Also +cairo_pattern_t + + + + -- cgit v1.2.1