/** * SECTION:cairo-surface * @Title: cairo_surface_t * @Short_Description: Base class for surfaces * @See_Also: #cairo_t, #cairo_pattern_t * * #cairo_surface_t is the abstract type representing all different drawing * targets that cairo can render to. The actual drawings are * performed using a cairo <firstterm>context</firstterm>. * * A cairo surface is created by using <firstterm>backend</firstterm>-specific * constructors, typically of the form * <function>cairo_<emphasis>backend</emphasis>_surface_create(<!-- -->)</function>. * * Most surface types allow accessing the surface without using Cairo * functions. If you do this, keep in mind that it is mandatory that you call * cairo_surface_flush() before reading from or writing to the surface and that * you must use cairo_surface_mark_dirty() after modifying it. * <example> * <title>Directly modifying an image surface</title> * <programlisting> * void * modify_image_surface (cairo_surface_t *surface) * { * unsigned char *data; * int width, height, stride; * * // flush to ensure all writing to the image was done * cairo_surface_flush (surface); * * // modify the image * data = cairo_image_surface_get_data (surface); * width = cairo_image_surface_get_width (surface); * height = cairo_image_surface_get_height (surface); * stride = cairo_image_surface_get_stride (surface); * modify_image_data (data, width, height, stride); * * // mark the image dirty so Cairo clears its caches. * cairo_surface_mark_dirty (surface); * } * </programlisting> * </example> * Note that for other surface types it might be necessary to acquire the * surface's device first. See cairo_device_acquire() for a discussion of * devices.
**/
/** * _cairo_surface_set_error: * @surface: a surface * @status: a status value indicating an error * * Atomically sets surface->status to @status and calls _cairo_error; * Does nothing if status is %CAIRO_STATUS_SUCCESS or any of the internal * status values. * * All assignments of an error status to surface->status should happen * through _cairo_surface_set_error(). Note that due to the nature of * the atomic operation, it is not safe to call this function on the * nil objects. * * The purpose of this function is to allow the user to set a * breakpoint in _cairo_error() to generate a stack trace for when the * user causes cairo to detect an error. * * Return value: the error status.
**/
cairo_int_status_t
_cairo_surface_set_error (cairo_surface_t *surface,
cairo_int_status_t status)
{ /* NOTHING_TO_DO is magic. We use it to break out of the inner-most * surface function, but anything higher just sees "success".
*/ if (status == CAIRO_INT_STATUS_NOTHING_TO_DO)
status = CAIRO_INT_STATUS_SUCCESS;
if (status == CAIRO_INT_STATUS_SUCCESS ||
status >= (int)CAIRO_INT_STATUS_LAST_STATUS) return status;
/* Don't overwrite an existing error. This preserves the first
* error, which is the most significant. */
_cairo_status_set_error (&surface->status, (cairo_status_t)status);
return _cairo_error (status);
}
/** * cairo_surface_get_type: * @surface: a #cairo_surface_t * * This function returns the type of the backend used to create * a surface. See #cairo_surface_type_t for available types. * * Return value: The type of @surface. * * Since: 1.2
**/
cairo_surface_type_t
cairo_surface_get_type (cairo_surface_t *surface)
{ /* We don't use surface->backend->type here so that some of the * special "wrapper" surfaces such as cairo_paginated_surface_t * can override surface->type with the type of the "child"
* surface. */ return surface->type;
}
/** * cairo_surface_get_content: * @surface: a #cairo_surface_t * * This function returns the content type of @surface which indicates * whether the surface contains color and/or alpha information. See * #cairo_content_t. * * Return value: The content type of @surface. * * Since: 1.2
**/
cairo_content_t
cairo_surface_get_content (cairo_surface_t *surface)
{ return surface->content;
}
/** * cairo_surface_status: * @surface: a #cairo_surface_t * * Checks whether an error has previously occurred for this * surface. * * Return value: %CAIRO_STATUS_SUCCESS, %CAIRO_STATUS_NULL_POINTER, * %CAIRO_STATUS_NO_MEMORY, %CAIRO_STATUS_READ_ERROR, * %CAIRO_STATUS_INVALID_CONTENT, %CAIRO_STATUS_INVALID_FORMAT, or * %CAIRO_STATUS_INVALID_VISUAL. * * Since: 1.0
**/
cairo_status_t
cairo_surface_status (cairo_surface_t *surface)
{ return surface->status;
}
do {
old = _cairo_atomic_uint_get (&unique_id);
id = old + 1; if (id == 0)
id = 1;
} while (! _cairo_atomic_uint_cmpxchg (&unique_id, old, id));
return id; #endif
}
/** * cairo_surface_get_device: * @surface: a #cairo_surface_t * * This function returns the device for a @surface. * See #cairo_device_t. * * Return value: The device for @surface or %NULL if the surface does * not have an associated device. * * Since: 1.10
**/
cairo_device_t *
cairo_surface_get_device (cairo_surface_t *surface)
{ if (unlikely (surface->status)) return _cairo_device_create_in_error (surface->status);
/** * cairo_surface_create_similar: * @other: an existing surface used to select the backend of the new surface * @content: the content for the new surface * @width: width of the new surface, (in device-space units) * @height: height of the new surface (in device-space units) * * Create a new surface that is as compatible as possible with an * existing surface. For example the new surface will have the same * device scale, fallback resolution and font options as * @other. Generally, the new surface will also use the same backend * as @other, unless that is not possible for some reason. The type of * the returned surface may be examined with * cairo_surface_get_type(). * * Initially the surface contents are all 0 (transparent if contents * have transparency, black otherwise.) * * Use cairo_surface_create_similar_image() if you need an image surface * which can be painted quickly to the target surface. * * Return value: a pointer to the newly allocated surface. The caller * owns the surface and should call cairo_surface_destroy() when done * with it. * * This function always returns a valid pointer, but it will return a * pointer to a "nil" surface if @other is already in an error state * or any other error occurs. * * Since: 1.0
**/
cairo_surface_t *
cairo_surface_create_similar (cairo_surface_t *other,
cairo_content_t content, int width, int height)
{
cairo_surface_t *surface;
cairo_status_t status;
cairo_solid_pattern_t pattern;
if (unlikely (other->status)) return _cairo_surface_create_in_error (other->status); if (unlikely (other->finished)) return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED); if (unlikely (width < 0 || height < 0)) return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE); if (unlikely (! CAIRO_CONTENT_VALID (content))) return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_CONTENT);
/* We inherit the device scale, so create a larger surface */
width = width * other->device_transform.xx;
height = height * other->device_transform.yy;
/** * cairo_surface_create_similar_image: * @other: an existing surface used to select the preference of the new surface * @format: the format for the new surface * @width: width of the new surface, (in pixels) * @height: height of the new surface (in pixels) * * Create a new image surface that is as compatible as possible for uploading * to and the use in conjunction with an existing surface. However, this surface * can still be used like any normal image surface. Unlike * cairo_surface_create_similar() the new image surface won't inherit * the device scale from @other. * * Initially the surface contents are all 0 (transparent if contents * have transparency, black otherwise.) * * Use cairo_surface_create_similar() if you don't need an image surface. * * Return value: a pointer to the newly allocated image surface. The caller * owns the surface and should call cairo_surface_destroy() when done * with it. * * This function always returns a valid pointer, but it will return a * pointer to a "nil" surface if @other is already in an error state * or any other error occurs. * * Since: 1.12
**/
cairo_surface_t *
cairo_surface_create_similar_image (cairo_surface_t *other,
cairo_format_t format, int width, int height)
{
cairo_surface_t *image;
if (unlikely (other->status)) return _cairo_surface_create_in_error (other->status); if (unlikely (other->finished)) return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED);
if (unlikely (width < 0 || height < 0)) return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE); if (unlikely (! CAIRO_FORMAT_VALID (format))) return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_FORMAT);
image = NULL; if (other->backend->create_similar_image)
image = other->backend->create_similar_image (other,
format, width, height); if (image == NULL)
image = cairo_image_surface_create (format, width, height);
assert (image->is_clear);
return image;
}
/** * _cairo_surface_map_to_image: * @surface: an existing surface used to extract the image from * @extents: limit the extraction to an rectangular region * * Returns an image surface that is the most efficient mechanism for * modifying the backing store of the target surface. The region * retrieved is limited to @extents. * * Note, the use of the original surface as a target or source whilst * it is mapped is undefined. The result of mapping the surface * multiple times is undefined. Calling cairo_surface_destroy() or * cairo_surface_finish() on the resulting image surface results in * undefined behavior. Changing the device transform of the image * surface or of @surface before the image surface is unmapped results * in undefined behavior. * * Assumes that @surface is valid (CAIRO_STATUS_SUCCESS, * non-finished). * * Return value: a pointer to the newly allocated image surface. The * caller must use _cairo_surface_unmap_image() to destroy this image * surface. * * This function always returns a valid pointer, but it will return a * pointer to a "nil" surface if @other is already in an error state * or any other error occurs. * * The returned image might have a %CAIRO_FORMAT_INVALID format.
**/
cairo_image_surface_t *
_cairo_surface_map_to_image (cairo_surface_t *surface, const cairo_rectangle_int_t *extents)
{
cairo_image_surface_t *image = NULL;
if (image == NULL)
image = _cairo_image_surface_clone_subimage (surface, extents);
return image;
}
/** * _cairo_surface_unmap_image: * @surface: the surface passed to _cairo_surface_map_to_image(). * @image: the currently mapped 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. * Afterwards, the image is destroyed. * * Using an image surface which wasn't returned by * _cairo_surface_map_to_image() results in undefined behavior. * * An image surface in error status can be passed to * _cairo_surface_unmap_image(). * * Return value: the unmap status. * * Even if the unmap status is not successful, @image is destroyed.
**/
cairo_int_status_t
_cairo_surface_unmap_image (cairo_surface_t *surface,
cairo_image_surface_t *image)
{
cairo_surface_pattern_t pattern;
cairo_rectangle_int_t extents;
cairo_clip_t *clip;
cairo_int_status_t status;
/* map_to_image can return error surfaces */ if (unlikely (image->base.status)) {
status = image->base.status; goto destroy;
}
/* If the image is untouched just skip the update */ if (image->base.serial == 0) {
status = CAIRO_STATUS_SUCCESS; goto destroy;
}
/* TODO: require unmap_image != NULL */ if (surface->backend->unmap_image &&
! _cairo_image_surface_is_clone (image))
{
status = surface->backend->unmap_image (surface, image); if (status != CAIRO_INT_STATUS_UNSUPPORTED) return status;
}
/* We have to apply the translate from map_to_image's extents.x and .y */
cairo_matrix_init_translate (&pattern.base.matrix,
image->base.device_transform.x0,
image->base.device_transform.y0);
/* And we also have to clip the operation to the image's extents */
extents.x = image->base.device_transform_inverse.x0;
extents.y = image->base.device_transform_inverse.y0;
extents.width = image->width;
extents.height = image->height;
clip = _cairo_clip_intersect_rectangle (NULL, &extents);
status = _cairo_surface_paint (surface,
CAIRO_OPERATOR_SOURCE,
&pattern.base,
clip);
/** * cairo_surface_map_to_image: * @surface: an existing surface used to extract the image from * @extents: limit the extraction to an rectangular region * * Returns an image surface that is the most efficient mechanism for * modifying the backing store of the target surface. The region retrieved * may be limited to the @extents or %NULL for the whole surface * * Note, the use of the original surface as a target or source whilst * it is mapped is undefined. The result of mapping the surface * multiple times is undefined. Calling cairo_surface_destroy() or * cairo_surface_finish() on the resulting image surface results in * undefined behavior. Changing the device transform of the image * surface or of @surface before the image surface is unmapped results * in undefined behavior. * * Return value: a pointer to the newly allocated image surface. The caller * must use cairo_surface_unmap_image() to destroy this image surface. * * This function always returns a valid pointer, but it will return a * pointer to a "nil" surface if @other is already in an error state * or any other error occurs. If the returned pointer does not have an * error status, it is guaranteed to be an image surface whose format * is not %CAIRO_FORMAT_INVALID. * * Since: 1.12
**/
cairo_surface_t *
cairo_surface_map_to_image (cairo_surface_t *surface, const cairo_rectangle_int_t *extents)
{
cairo_rectangle_int_t rect;
cairo_image_surface_t *image;
cairo_status_t status;
if (unlikely (surface->status)) return _cairo_surface_create_in_error (surface->status); if (unlikely (surface->finished)) return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED);
if (extents == NULL) { if (unlikely (! surface->backend->get_extents (surface, &rect))) return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);
/* If this surface is bounded, we can't map parts
* that are outside of it. */ if (likely (surface->backend->get_extents (surface, &surface_extents))) { if (unlikely (! _cairo_rectangle_contains_rectangle (&surface_extents, extents))) return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);
}
}
/** * cairo_surface_unmap_image: * @surface: the surface passed to cairo_surface_map_to_image(). * @image: the currently mapped 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. * Afterwards, the image is destroyed. * * Using an image surface which wasn't returned by cairo_surface_map_to_image() * results in undefined behavior. * * Since: 1.12
**/ void
cairo_surface_unmap_image (cairo_surface_t *surface,
cairo_surface_t *image)
{
cairo_int_status_t status = CAIRO_STATUS_SUCCESS;
if (unlikely (surface->status)) {
status = surface->status; goto error;
} if (unlikely (surface->finished)) {
status = _cairo_error (CAIRO_STATUS_SURFACE_FINISHED); goto error;
} if (unlikely (image->status)) {
status = image->status; goto error;
} if (unlikely (image->finished)) {
status = _cairo_error (CAIRO_STATUS_SURFACE_FINISHED); goto error;
} if (unlikely (! _cairo_surface_is_image (image))) {
status = _cairo_error (CAIRO_STATUS_SURFACE_TYPE_MISMATCH); goto error;
}
status = _cairo_surface_unmap_image (surface,
(cairo_image_surface_t *) image); if (unlikely (status))
_cairo_surface_set_error (surface, status);
if (color) {
_cairo_pattern_init_solid (&pattern, color);
status = _cairo_surface_paint (surface,
color == CAIRO_COLOR_TRANSPARENT ?
CAIRO_OPERATOR_CLEAR : CAIRO_OPERATOR_SOURCE,
&pattern.base, NULL); if (unlikely (status)) {
cairo_surface_destroy (surface);
surface = _cairo_surface_create_in_error (status);
}
}
return surface;
}
/** * cairo_surface_reference: * @surface: a #cairo_surface_t * * Increases the reference count on @surface by one. This prevents * @surface from being destroyed until a matching call to * cairo_surface_destroy() is made. * * Use cairo_surface_get_reference_count() to get the number of * references to a #cairo_surface_t. * * Return value: the referenced #cairo_surface_t. * * Since: 1.0
**/
cairo_surface_t *
cairo_surface_reference (cairo_surface_t *surface)
{ if (surface == NULL ||
CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count)) return surface;
/** * cairo_surface_destroy: * @surface: a #cairo_surface_t * * Decreases the reference count on @surface by one. If the result is * zero, then @surface and all associated resources are freed. See * cairo_surface_reference(). * * Since: 1.0
**/ void
cairo_surface_destroy (cairo_surface_t *surface)
{ if (surface == NULL ||
CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count)) return;
if (! _cairo_reference_count_dec_and_test (&surface->ref_count)) return;
assert (surface->snapshot_of == NULL);
if (! surface->finished) {
_cairo_surface_finish_snapshots (surface); /* We may have been referenced by a snapshot prior to have * detaching it with the copy-on-write.
*/ if (CAIRO_REFERENCE_COUNT_GET_VALUE (&surface->ref_count)) return;
_cairo_surface_finish (surface);
}
if (surface->damage)
_cairo_damage_destroy (surface->damage);
if (surface->foreground_source)
cairo_pattern_destroy (surface->foreground_source);
if (surface->owns_device)
cairo_device_destroy (surface->device);
if (surface->has_font_options)
_cairo_font_options_fini (&surface->font_options);
assert (surface->snapshot_of == NULL);
assert (! _cairo_surface_has_snapshots (surface)); /* paranoid check that nobody took a reference whilst finishing */
assert (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count));
free (surface);
}
/** * cairo_surface_get_reference_count: * @surface: a #cairo_surface_t * * Returns the current reference count of @surface. * * Return value: the current reference count of @surface. If the * object is a nil object, 0 will be returned. * * Since: 1.4
**/ unsignedint
cairo_surface_get_reference_count (cairo_surface_t *surface)
{ if (surface == NULL ||
CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count)) return 0;
/* update the snapshots *before* we declare the surface as finished */
surface->_finishing = TRUE;
status = _cairo_surface_flush (surface, 0);
(void) status;
}
/* call finish even if in error mode */ if (surface->backend->finish) {
status = surface->backend->finish (surface); if (unlikely (status))
_cairo_surface_set_error (surface, status);
}
/** * cairo_surface_finish: * @surface: the #cairo_surface_t to finish * * This function finishes the surface and drops all references to * external resources. For example, for the Xlib backend it means * that cairo will no longer access the drawable, which can be freed. * After calling cairo_surface_finish() the only valid operations on a * surface are checking status, getting and setting user, referencing * and destroying, and flushing and finishing it. * Further drawing to the surface will not affect the * surface but will instead trigger a %CAIRO_STATUS_SURFACE_FINISHED * error. * * When the last call to cairo_surface_destroy() decreases the * reference count to zero, cairo will call cairo_surface_finish() if * it hasn't been called already, before freeing the resources * associated with the surface. * * Since: 1.0
**/ void
cairo_surface_finish (cairo_surface_t *surface)
{ if (surface == NULL) return;
if (CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count)) return;
if (surface->finished) return;
/* We have to be careful when decoupling potential reference cycles */
cairo_surface_reference (surface);
_cairo_surface_finish_snapshots (surface); /* XXX need to block and wait for snapshot references */
_cairo_surface_finish (surface);
cairo_surface_destroy (surface);
}
/** * _cairo_surface_release_device_reference: * @surface: a #cairo_surface_t * * This function makes @surface release the reference to its device. The * function is intended to be used for avoiding cycling references for * surfaces that are owned by their device, for example cache surfaces. * Note that the @surface will still assume that the device is available. * So it is the caller's responsibility to ensure the device stays around * until the @surface is destroyed. Just calling cairo_surface_finish() is * not enough.
**/ void
_cairo_surface_release_device_reference (cairo_surface_t *surface)
{
assert (surface->owns_device);
/** * cairo_surface_get_user_data: * @surface: a #cairo_surface_t * @key: the address of the #cairo_user_data_key_t the user data was * attached to * * Return user data previously attached to @surface using the specified * key. If no user data has been attached with the given key this * function returns %NULL. * * Return value: the user data previously attached or %NULL. * * Since: 1.0
**/ void *
cairo_surface_get_user_data (cairo_surface_t *surface, const cairo_user_data_key_t *key)
{ /* Prevent reads of the array during teardown */ if (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count)) return NULL;
/** * cairo_surface_set_user_data: * @surface: a #cairo_surface_t * @key: the address of a #cairo_user_data_key_t to attach the user data to * @user_data: the user data to attach to the surface * @destroy: a #cairo_destroy_func_t which will be called when the * surface is destroyed or when new user data is attached using the * same key. * * Attach user data to @surface. To remove user data from a surface, * call this function with the key that was used to set it and %NULL * for @data. * * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a * slot could not be allocated for the user data. * * Since: 1.0
**/
cairo_status_t
cairo_surface_set_user_data (cairo_surface_t *surface, const cairo_user_data_key_t *key, void *user_data,
cairo_destroy_func_t destroy)
{ if (CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count)) return surface->status;
if (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count)) return _cairo_error (CAIRO_STATUS_SURFACE_FINISHED);
/** * cairo_surface_get_mime_data: * @surface: a #cairo_surface_t * @mime_type: the mime type of the image data * @data: the image data to attached to the surface * @length: the length of the image data * * Return mime data previously attached to @surface using the * specified mime type. If no data has been attached with the given * mime type, @data is set %NULL. * * Since: 1.10
**/ void
cairo_surface_get_mime_data (cairo_surface_t *surface, constchar *mime_type, constunsignedchar **data, unsignedlong *length)
{
cairo_user_data_slot_t *slots; int i, num_slots;
*data = NULL;
*length = 0;
/* Prevent reads of the array during teardown */ if (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count)) return;
/* The number of mime-types attached to a surface is usually small, * typically zero. Therefore it is quicker to do a strcmp() against * each key than it is to intern the string (i.e. compute a hash, * search the hash table, and do a final strcmp).
*/
num_slots = surface->mime_data.num_elements;
slots = _cairo_array_index (&surface->mime_data, 0); for (i = 0; i < num_slots; i++) { if (slots[i].key != NULL && strcmp ((char *) slots[i].key, mime_type) == 0) {
cairo_mime_data_t *mime_data = slots[i].user_data;
cairo_bool_t
_cairo_surface_has_mime_image (cairo_surface_t *surface)
{
cairo_user_data_slot_t *slots; int i, j, num_slots;
/* Prevent reads of the array during teardown */ if (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count)) returnFALSE;
/* The number of mime-types attached to a surface is usually small, * typically zero. Therefore it is quicker to do a strcmp() against * each key than it is to intern the string (i.e. compute a hash, * search the hash table, and do a final strcmp).
*/
num_slots = surface->mime_data.num_elements;
slots = _cairo_array_index (&surface->mime_data, 0); for (i = 0; i < num_slots; i++) { if (slots[i].key != NULL) { for (j = 0; j < ARRAY_LENGTH (_cairo_surface_image_mime_types); j++) { if (strcmp ((char *) slots[i].key, _cairo_surface_image_mime_types[j]) == 0) returnTRUE;
}
}
}
returnFALSE;
}
/** * CAIRO_MIME_TYPE_CCITT_FAX: * * Group 3 or Group 4 CCITT facsimile encoding (International * Telecommunication Union, Recommendations T.4 and T.6.) * * Since: 1.16
**/
/** * CAIRO_MIME_TYPE_CCITT_FAX_PARAMS: * * Decode parameters for Group 3 or Group 4 CCITT facsimile encoding. * See [CCITT Fax Images][ccitt]. * * Since: 1.16
**/
/** * CAIRO_MIME_TYPE_JBIG2: * * Joint Bi-level Image Experts Group image coding standard (ISO/IEC 11544). * * Since: 1.14
**/
/** * CAIRO_MIME_TYPE_JBIG2_GLOBAL: * * Joint Bi-level Image Experts Group image coding standard (ISO/IEC 11544) global segment. * * Since: 1.14
**/
/** * CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID: * * An unique identifier shared by a JBIG2 global segment and all JBIG2 images * that depend on the global segment. * * Since: 1.14
**/
/** * CAIRO_MIME_TYPE_JP2: * * The Joint Photographic Experts Group (JPEG) 2000 image coding standard (ISO/IEC 15444-1). * * Since: 1.10
**/
/** * CAIRO_MIME_TYPE_JPEG: * * The Joint Photographic Experts Group (JPEG) image coding standard (ISO/IEC 10918-1). * * Since: 1.10
**/
/** * CAIRO_MIME_TYPE_PNG: * * The Portable Network Graphics image file format (ISO/IEC 15948). * * Since: 1.10
**/
/** * CAIRO_MIME_TYPE_URI: * * URI for an image file (unofficial MIME type). * * Since: 1.10
**/
/** * CAIRO_MIME_TYPE_UNIQUE_ID: * * Unique identifier for a surface (cairo specific MIME type). All surfaces with * the same unique identifier will only be embedded once. * * Since: 1.12
**/
/** * cairo_surface_set_mime_data: * @surface: a #cairo_surface_t * @mime_type: the MIME type of the image data * @data: the image data to attach to the surface * @length: the length of the image data * @destroy: a #cairo_destroy_func_t which will be called when the * surface is destroyed or when new image data is attached using the * same mime type. * @closure: the data to be passed to the @destroy notifier * * Attach an image in the format @mime_type to @surface. To remove * the data from a surface, call this function with same mime type * and %NULL for @data. * * The attached image (or filename) data can later be used by backends * which support it (currently: PDF, PS, SVG and Win32 Printing * surfaces) to emit this data instead of making a snapshot of the * @surface. This approach tends to be faster and requires less * memory and disk space. * * The recognized MIME types are the following: %CAIRO_MIME_TYPE_JPEG, * %CAIRO_MIME_TYPE_PNG, %CAIRO_MIME_TYPE_JP2, %CAIRO_MIME_TYPE_URI, * %CAIRO_MIME_TYPE_UNIQUE_ID, %CAIRO_MIME_TYPE_JBIG2, * %CAIRO_MIME_TYPE_JBIG2_GLOBAL, %CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID, * %CAIRO_MIME_TYPE_CCITT_FAX, %CAIRO_MIME_TYPE_CCITT_FAX_PARAMS. * * See corresponding backend surface docs for details about which MIME * types it can handle. Caution: the associated MIME data will be * discarded if you draw on the surface afterwards. Use this function * with care. * * Even if a backend supports a MIME type, that does not mean cairo * will always be able to use the attached MIME data. For example, if * the backend does not natively support the compositing operation used * to apply the MIME data to the backend. In that case, the MIME data * will be ignored. Therefore, to apply an image in all cases, it is best * to create an image surface which contains the decoded image data and * then attach the MIME data to that. This ensures the image will always * be used while still allowing the MIME data to be used whenever * possible. * * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a * slot could not be allocated for the user data. * * Since: 1.10
**/
cairo_status_t
cairo_surface_set_mime_data (cairo_surface_t *surface, constchar *mime_type, constunsignedchar *data, unsignedlong length,
cairo_destroy_func_t destroy, void *closure)
{
cairo_status_t status;
cairo_mime_data_t *mime_data;
if (CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count)) return surface->status;
if (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count)) return _cairo_error (CAIRO_STATUS_SURFACE_FINISHED);
if (unlikely (surface->status)) return surface->status; if (unlikely (surface->finished)) return _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
status = _cairo_intern_string (&mime_type, -1); if (unlikely (status)) return _cairo_surface_set_error (surface, status);
if (data != NULL) {
mime_data = _cairo_malloc (sizeof (cairo_mime_data_t)); if (unlikely (mime_data == NULL)) return _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_NO_MEMORY));
if (src->status) return _cairo_surface_set_error (dst, src->status);
/* first copy the mime-data, discarding any already set on dst */
status = _cairo_user_data_array_copy (&dst->mime_data, &src->mime_data); if (unlikely (status)) return _cairo_surface_set_error (dst, status);
/* now increment the reference counters for the copies */
_cairo_user_data_array_foreach (&dst->mime_data,
_cairo_mime_data_reference,
NULL);
dst->is_clear = FALSE;
return CAIRO_STATUS_SUCCESS;
}
/** * _cairo_surface_set_font_options: * @surface: a #cairo_surface_t * @options: a #cairo_font_options_t object that contains the * options to use for this surface instead of backend's default * font options. * * Sets the default font rendering options for the surface. * This is useful to correctly propagate default font options when * falling back to an image surface in a backend implementation. * This affects the options returned in cairo_surface_get_font_options(). * * If @options is %NULL the surface options are reset to those of * the backend default.
**/ void
_cairo_surface_set_font_options (cairo_surface_t *surface,
cairo_font_options_t *options)
{ if (surface->status) return;
assert (surface->snapshot_of == NULL);
if (surface->finished) {
_cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED)); return;
}
/** * cairo_surface_get_font_options: * @surface: a #cairo_surface_t * @options: a #cairo_font_options_t object into which to store * the retrieved options. All existing values are overwritten * * Retrieves the default font rendering options for the surface. * This allows display surfaces to report the correct subpixel order * for rendering on them, print surfaces to disable hinting of * metrics and so forth. The result can then be used with * cairo_scaled_font_create(). * * Since: 1.0
**/ void
cairo_surface_get_font_options (cairo_surface_t *surface,
cairo_font_options_t *options)
{ if (cairo_font_options_status (options)) return;
if (surface->status) {
_cairo_font_options_init_default (options); return;
}
if (! surface->has_font_options) {
surface->has_font_options = TRUE;
/** * cairo_surface_set_subpixel_antialiasing: * @surface: a #cairo_surface_t * * Sets whether the surface permits subpixel antialiasing. By default, * surfaces permit subpixel antialiasing. * * Enabling subpixel antialiasing for CONTENT_COLOR_ALPHA surfaces generally * requires that the pixels in the areas under a subpixel antialiasing * operation already be opaque.
**/ void
cairo_surface_set_subpixel_antialiasing (cairo_surface_t *surface,
cairo_subpixel_antialiasing_t enabled)
{ if (surface->status) return;
if (surface->finished) {
_cairo_surface_set_error (surface, CAIRO_STATUS_SURFACE_FINISHED); return;
}
/** * cairo_surface_get_subpixel_antialiasing: * @surface: a #cairo_surface_t * * Gets whether the surface supports subpixel antialiasing. By default, * CAIRO_CONTENT_COLOR surfaces support subpixel antialiasing but other * surfaces do not.
**/
cairo_subpixel_antialiasing_t
cairo_surface_get_subpixel_antialiasing (cairo_surface_t *surface)
{ if (surface->status) return CAIRO_SUBPIXEL_ANTIALIASING_DISABLED;
cairo_status_t
_cairo_surface_flush (cairo_surface_t *surface, unsigned flags)
{ /* update the current snapshots *before* the user updates the surface */
_cairo_surface_detach_snapshots (surface); if (surface->snapshot_of != NULL)
_cairo_surface_detach_snapshot (surface);
_cairo_surface_detach_mime_data (surface);
return __cairo_surface_flush (surface, flags);
}
/** * cairo_surface_flush: * @surface: a #cairo_surface_t * * Do any pending drawing for the surface and also restore any temporary * modifications cairo has made to the surface's state. This function * must be called before switching from drawing on the surface with * cairo to drawing on it directly with native APIs, or accessing its * memory outside of Cairo. If the surface doesn't support direct * access, then this function does nothing. * * Since: 1.0
**/ void
cairo_surface_flush (cairo_surface_t *surface)
{
cairo_status_t status;
if (surface->status) return;
if (surface->finished) return;
status = _cairo_surface_flush (surface, 0); if (unlikely (status))
_cairo_surface_set_error (surface, status);
}
/** * cairo_surface_mark_dirty: * @surface: a #cairo_surface_t * * Tells cairo that drawing has been done to surface using means other * than cairo, and that cairo should reread any cached areas. Note * that you must call cairo_surface_flush() before doing such drawing. * * Since: 1.0
**/ void
cairo_surface_mark_dirty (cairo_surface_t *surface)
{
cairo_rectangle_int_t extents;
if (unlikely (surface->status)) return; if (unlikely (surface->finished)) {
_cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED)); return;
}
/** * cairo_surface_mark_dirty_rectangle: * @surface: a #cairo_surface_t * @x: X coordinate of dirty rectangle * @y: Y coordinate of dirty rectangle * @width: width of dirty rectangle * @height: height of dirty rectangle * * Like cairo_surface_mark_dirty(), but drawing has been done only to * the specified rectangle, so that cairo can retain cached contents * for other parts of the surface. * * Any cached clip set on the surface will be reset by this function, * to make sure that future cairo calls have the clip set that they * expect. * * Since: 1.0
**/ void
cairo_surface_mark_dirty_rectangle (cairo_surface_t *surface, int x, int y, int width, int height)
{
cairo_status_t status;
if (unlikely (surface->status)) return;
assert (surface->snapshot_of == NULL);
if (unlikely (surface->finished)) {
_cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED)); return;
}
/* The application *should* have called cairo_surface_flush() before * modifying the surface independently of cairo (and thus having to
* call mark_dirty()). */
assert (! _cairo_surface_has_snapshots (surface));
assert (! _cairo_surface_has_mime_data (surface));
surface->is_clear = FALSE;
surface->serial++;
if (surface->damage) {
cairo_box_t box;
box.p1.x = x;
box.p1.y = y;
box.p2.x = x + width;
box.p2.y = y + height;
if (surface->backend->mark_dirty_rectangle != NULL) { /* XXX: FRAGILE: We're ignoring the scaling component of * device_transform here. I don't know what the right thing to * do would actually be if there were some scaling here, but * we avoid this since device_transfom scaling is not exported
* publicly and mark_dirty is not used internally. */
status = surface->backend->mark_dirty_rectangle (surface,
x + surface->device_transform.x0,
y + surface->device_transform.y0,
width, height);
if (unlikely (status))
_cairo_surface_set_error (surface, status);
}
}
/** * cairo_surface_set_device_scale: * @surface: a #cairo_surface_t * @x_scale: a scale factor in the X direction * @y_scale: a scale factor in the Y direction * * Sets a scale that is multiplied to the device coordinates determined * by the CTM when drawing to @surface. One common use for this is to * render to very high resolution display devices at a scale factor, so * that code that assumes 1 pixel will be a certain size will still work. * Setting a transformation via cairo_scale() isn't * sufficient to do this, since functions like * cairo_device_to_user() will expose the hidden scale. * * Note that the scale affects drawing to the surface as well as * using the surface in a source pattern. * * Since: 1.14
**/ void
cairo_surface_set_device_scale (cairo_surface_t *surface, double x_scale, double y_scale)
{
cairo_status_t status;
if (unlikely (surface->status)) return;
assert (surface->snapshot_of == NULL);
if (unlikely (surface->finished)) {
_cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED)); return;
}
status = _cairo_surface_begin_modification (surface); if (unlikely (status)) {
_cairo_surface_set_error (surface, status); return;
}
/** * cairo_surface_get_device_scale: * @surface: a #cairo_surface_t * @x_scale: the scale in the X direction, in device units * @y_scale: the scale in the Y direction, in device units * * This function returns the previous device scale set by * cairo_surface_set_device_scale(). * * Since: 1.14
**/ void
cairo_surface_get_device_scale (cairo_surface_t *surface, double *x_scale, double *y_scale)
{ if (x_scale)
*x_scale = surface->device_transform.xx; if (y_scale)
*y_scale = surface->device_transform.yy;
}
/** * cairo_surface_set_device_offset: * @surface: a #cairo_surface_t * @x_offset: the offset in the X direction, in device units * @y_offset: the offset in the Y direction, in device units * * Sets an offset that is added to the device coordinates determined * by the CTM when drawing to @surface. One use case for this function * is when we want to create a #cairo_surface_t that redirects drawing * for a portion of an onscreen surface to an offscreen surface in a * way that is completely invisible to the user of the cairo * API. Setting a transformation via cairo_translate() isn't * sufficient to do this, since functions like * cairo_device_to_user() will expose the hidden offset. * * Note that the offset affects drawing to the surface as well as * using the surface in a source pattern. * * Since: 1.0
**/ void
cairo_surface_set_device_offset (cairo_surface_t *surface, double x_offset, double y_offset)
{
cairo_status_t status;
if (unlikely (surface->status)) return;
assert (surface->snapshot_of == NULL);
if (unlikely (surface->finished)) {
_cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED)); return;
}
status = _cairo_surface_begin_modification (surface); if (unlikely (status)) {
_cairo_surface_set_error (surface, status); return;
}
/** * cairo_surface_get_device_offset: * @surface: a #cairo_surface_t * @x_offset: the offset in the X direction, in device units * @y_offset: the offset in the Y direction, in device units * * This function returns the previous device offset set by * cairo_surface_set_device_offset(). * * Since: 1.2
**/ void
cairo_surface_get_device_offset (cairo_surface_t *surface, double *x_offset, double *y_offset)
{ if (x_offset)
*x_offset = surface->device_transform.x0; if (y_offset)
*y_offset = surface->device_transform.y0;
}
/** * cairo_surface_set_fallback_resolution: * @surface: a #cairo_surface_t * @x_pixels_per_inch: horizontal setting for pixels per inch * @y_pixels_per_inch: vertical setting for pixels per inch * * Set the horizontal and vertical resolution for image fallbacks. * * When certain operations aren't supported natively by a backend, * cairo will fallback by rendering operations to an image and then * overlaying that image onto the output. For backends that are * natively vector-oriented, this function can be used to set the * resolution used for these image fallbacks, (larger values will * result in more detailed images, but also larger file sizes). * * Some examples of natively vector-oriented backends are the ps, pdf, * and svg backends. * * For backends that are natively raster-oriented, image fallbacks are * still possible, but they are always performed at the native * device resolution. So this function has no effect on those * backends. * * Note: The fallback resolution only takes effect at the time of * completing a page (with cairo_show_page() or cairo_copy_page()) so * there is currently no way to have more than one fallback resolution * in effect on a single page. * * The default fallback resolution is 300 pixels per inch in both * dimensions. * * Since: 1.2
**/ void
cairo_surface_set_fallback_resolution (cairo_surface_t *surface, double x_pixels_per_inch, double y_pixels_per_inch)
{
cairo_status_t status;
if (unlikely (surface->status)) return;
assert (surface->snapshot_of == NULL);
if (unlikely (surface->finished)) {
_cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED)); return;
}
if (x_pixels_per_inch <= 0 || y_pixels_per_inch <= 0) { /* XXX Could delay raising the error until we fallback, but throwing * the error here means that we can catch the real culprit.
*/
_cairo_surface_set_error (surface, CAIRO_STATUS_INVALID_MATRIX); return;
}
status = _cairo_surface_begin_modification (surface); if (unlikely (status)) {
_cairo_surface_set_error (surface, status); return;
}
/** * cairo_surface_get_fallback_resolution: * @surface: a #cairo_surface_t * @x_pixels_per_inch: horizontal pixels per inch * @y_pixels_per_inch: vertical pixels per inch * * This function returns the previous fallback resolution set by * cairo_surface_set_fallback_resolution(), or default fallback * resolution if never set. * * Since: 1.8
**/ void
cairo_surface_get_fallback_resolution (cairo_surface_t *surface, double *x_pixels_per_inch, double *y_pixels_per_inch)
{ if (x_pixels_per_inch)
*x_pixels_per_inch = surface->x_fallback_resolution; if (y_pixels_per_inch)
*y_pixels_per_inch = surface->y_fallback_resolution;
}
/** * _cairo_surface_acquire_source_image: * @surface: a #cairo_surface_t * @image_out: location to store a pointer to an image surface that * has identical contents to @surface. This surface could be @surface * itself, a surface held internal to @surface, or it could be a new * surface with a copy of the relevant portion of @surface. * @image_extra: location to store image specific backend data * * Gets an image surface to use when drawing as a fallback when drawing with * @surface as a source. _cairo_surface_release_source_image() must be called * when finished. * * Return value: %CAIRO_STATUS_SUCCESS if an image was stored in @image_out. * %CAIRO_INT_STATUS_UNSUPPORTED if an image cannot be retrieved for the specified * surface. Or %CAIRO_STATUS_NO_MEMORY.
**/
cairo_status_t
_cairo_surface_acquire_source_image (cairo_surface_t *surface,
cairo_image_surface_t **image_out, void **image_extra)
{
cairo_status_t status;
if (unlikely (surface->status)) return surface->status;
assert (!surface->finished);
if (surface->backend->acquire_source_image == NULL) return CAIRO_INT_STATUS_UNSUPPORTED;
status = surface->backend->acquire_source_image (surface,
image_out, image_extra); if (unlikely (status)) return _cairo_surface_set_error (surface, status);
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung und die Messung sind noch experimentell.
