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/html/cairo-Raster-Sources.html | 794 +++++++++++++++++++++ 1 file changed, 794 insertions(+) create mode 100644 libs/cairo-1.16.0/doc/public/html/cairo-Raster-Sources.html (limited to 'libs/cairo-1.16.0/doc/public/html/cairo-Raster-Sources.html') diff --git a/libs/cairo-1.16.0/doc/public/html/cairo-Raster-Sources.html b/libs/cairo-1.16.0/doc/public/html/cairo-Raster-Sources.html new file mode 100644 index 0000000..499dc96 --- /dev/null +++ b/libs/cairo-1.16.0/doc/public/html/cairo-Raster-Sources.html @@ -0,0 +1,794 @@ + + + + +Raster Sources: Cairo: A Vector Graphics Library + + + + + + + + + + + + + + + + +
+
+
+ + +
+

Raster Sources

+

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_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 ()

+
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 ()

+
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 ()

+
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 ()

+
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 ()

+
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_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 ()

+
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_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 ()

+
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_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_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 ()

+
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_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_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 ()

+
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

+
+
+
+
Generated by GTK-Doc V1.27
+ + \ No newline at end of file -- cgit v1.2.1