cairoLib.Surface.Surface Class Reference

List of all members.

Detailed Description

Description.


Public Member Functions

cairo_surface_tgetSurfaceStruct ()
 this (cairo_surface_t *cairo_surface)
 Sets our main struct and passes it to the parent class.
cairo_surface_tcreateSimilar (cairo_content_t content, int width, int height)
 Create a new surface that is as compatible as possible with an existing surface.
void destroy ()
 Decreases the reference count on surface by one.
void finish ()
 This function finishes the surface and drops all references to external resources.
void flush ()
 Do any pending drawing for the surface and also restore any temporary modification's cairo has made to the surface's state.
void getFontOptions (cairo_font_options_t *options)
 Retrieves the default font rendering options for the surface.
cairo_content_t getContent ()
 surface: a cairo_surface_t Returns: The content type of surface which indicates whether the surface contains color and/or alpha information.
cairo_status_t setUserData (cairo_user_data_key_t *key, void *userData, cairo_destroy_func_t destroy)
 Attach user data to surface.
void * getUserData (cairo_user_data_key_t *key)
 Return user data previously attached to surface using the specified key.
void markDirty ()
 Tells cairo that drawing has been done to surface using means other than cairo, and that cairo should reread any cached areas.
void markDirtyRectangle (int x, int y, int width, int height)
 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.
cairo_surface_treference ()
 Increases the reference count on surface by one.
void setDeviceOffset (double xOffset, double yOffset)
 Sets an offset that is added to the device coordinates determined by the CTM when drawing to surface.
void getDeviceOffset (double *xOffset, double *yOffset)
 This function returns the previous device offset set by cairo_surface_set_device_offset().
void setFallbackResolution (double xPixelsPerInch, double yPixelsPerInch)
 Set the horizontal and vertical resolution for image fallbacks.
cairo_status_t status ()
 Checks whether an error has previously occurred for this surface.
cairo_surface_type_t getType ()
 This function returns the type of the backend used to create a surface.
ubyte * imageSurfaceGetData ()
 Get a pointer to the data of the image surface, for direct inspection or modification.
cairo_format_t imageSurfaceGetFormat ()
 Get the format of the surface.
int imageSurfaceGetWidth ()
 Get the width of the image surface in pixels.
int imageSurfaceGetHeight ()
 Get the height of the image surface in pixels.
int imageSurfaceGetStride ()
 Get the stride of the image surface in bytes surface: a cairo_image_surface_t Returns: the stride of the image surface in bytes (or 0 if surface is not an image surface).

Static Public Member Functions

static cairo_surface_timageSurfaceCreate (cairo_format_t format, int width, int height)
 Creates an image surface of the specified format and dimensions.
static cairo_surface_timageSurfaceCreateForData (ubyte *data, cairo_format_t format, int width, int height, int stride)
 Creates an image surface for the provided pixel data.

Protected Member Functions

void * getStruct ()
 the main Gtk struct as a void*

Protected Attributes

cairo_surface_tcairo_surface
 the main Gtk struct


Constructor & Destructor Documentation

cairoLib.Surface.Surface.this ( cairo_surface_t cairo_surface  ) 

Sets our main struct and passes it to the parent class.


Member Function Documentation

cairo_surface_t* cairoLib.Surface.Surface.createSimilar ( cairo_content_t  content,
int  width,
int  height 
)

Create a new surface that is as compatible as possible with an existing surface.

For example the new surface will have the same 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.) 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) Returns: 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.

void cairoLib.Surface.Surface.destroy (  ) 

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(). surface: a cairo_t

void cairoLib.Surface.Surface.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 getting and setting user data and referencing and destroying 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. surface: the cairo_surface_t to finish

void cairoLib.Surface.Surface.flush (  ) 

Do any pending drawing for the surface and also restore any temporary modification's 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. If the surface doesn't support direct access, then this function does nothing. surface: a cairo_surface_t

cairo_content_t cairoLib.Surface.Surface.getContent (  ) 

surface: a cairo_surface_t Returns: The content type of surface which indicates whether the surface contains color and/or alpha information.

See cairo_content_t. Since 1.2

void cairoLib.Surface.Surface.getDeviceOffset ( double *  xOffset,
double *  yOffset 
)

This function returns the previous device offset set by 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 Since 1.2

void cairoLib.Surface.Surface.getFontOptions ( cairo_font_options_t options  ) 

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(). surface: a cairo_surface_t options: a cairo_font_options_t object into which to store the retrieved options. All existing values are overwritten

void* cairoLib.Surface.Surface.getStruct (  )  [protected]

the main Gtk struct as a void*

cairo_surface_t* cairoLib.Surface.Surface.getSurfaceStruct (  ) 

cairo_surface_type_t cairoLib.Surface.Surface.getType (  ) 

This function returns the type of the backend used to create a surface.

See cairo_surface_type_t for available types. surface: a cairo_surface_t Returns: The type of surface. Since 1.2

void* cairoLib.Surface.Surface.getUserData ( cairo_user_data_key_t key  ) 

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. surface: a cairo_surface_t key: the address of the cairo_user_data_key_t the user data was attached to Returns: the user data previously attached or NULL.

static cairo_surface_t* cairoLib.Surface.Surface.imageSurfaceCreate ( cairo_format_t  format,
int  width,
int  height 
) [static]

Creates an image surface of the specified format and dimensions.

Initially the surface contents are all 0. (Specifically, within each pixel, each color or alpha channel belonging to format will be 0. The contents of bits within a pixel, but not belonging to the given format are undefined). format: format of pixels in the surface to create width: width of the surface, in pixels height: height of the surface, in pixels Returns: a pointer to the newly created 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 an error such as out of memory occurs. You can use cairo_surface_status() to check for this.

static cairo_surface_t* cairoLib.Surface.Surface.imageSurfaceCreateForData ( ubyte *  data,
cairo_format_t  format,
int  width,
int  height,
int  stride 
) [static]

Creates an image surface for the provided pixel data.

The output buffer must be kept around until the cairo_surface_t is destroyed or cairo_surface_finish() is called on the surface. The initial contents of buffer will be used as the inital image contents; you must explicitely clear the buffer, using, for example, cairo_rectangle() and cairo_fill() if you want it cleared. data: a pointer to a buffer supplied by the application in which to write contents. format: the format of pixels in the buffer width: the width of the image to be stored in the buffer height: the height of the image to be stored in the buffer stride: the number of bytes between the start of rows in the buffer. Having this be specified separate from width allows for padding at the end of rows, or for writing to a subportion of a larger image. Returns: a pointer to the newly created 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 an error such as out of memory occurs. You can use cairo_surface_status() to check for this. See cairo_surface_set_user_data() for a means of attaching a destroy-notification fallback to the surface if necessary.

ubyte* cairoLib.Surface.Surface.imageSurfaceGetData (  ) 

Get a pointer to the data of the image surface, for direct inspection or modification.

surface: a cairo_image_surface_t Returns: a pointer to the image data of this surface or NULL if surface is not an image surface. Since 1.2

cairo_format_t cairoLib.Surface.Surface.imageSurfaceGetFormat (  ) 

Get the format of the surface.

surface: a cairo_image_surface_t Returns: the format of the surface Since 1.2

int cairoLib.Surface.Surface.imageSurfaceGetHeight (  ) 

Get the height of the image surface in pixels.

surface: a cairo_image_surface_t Returns: the height of the surface in pixels.

int cairoLib.Surface.Surface.imageSurfaceGetStride (  ) 

Get the stride of the image surface in bytes surface: a cairo_image_surface_t Returns: the stride of the image surface in bytes (or 0 if surface is not an image surface).

The stride is the distance in bytes from the beginning of one row of the image data to the beginning of the next row. Since 1.2

int cairoLib.Surface.Surface.imageSurfaceGetWidth (  ) 

Get the width of the image surface in pixels.

surface: a cairo_image_surface_t Returns: the width of the surface in pixels.

void cairoLib.Surface.Surface.markDirty (  ) 

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. surface: a cairo_surface_t

void cairoLib.Surface.Surface.markDirtyRectangle ( int  x,
int  y,
int  width,
int  height 
)

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. 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

cairo_surface_t* cairoLib.Surface.Surface.reference (  ) 

Increases the reference count on surface by one.

This prevents surface from being destroyed until a matching call to cairo_surface_destroy() is made. surface: a cairo_surface_t Returns: the referenced cairo_surface_t.

void cairoLib.Surface.Surface.setDeviceOffset ( double  xOffset,
double  yOffset 
)

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. 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

void cairoLib.Surface.Surface.setFallbackResolution ( double  xPixelsPerInch,
double  yPixelsPerInch 
)

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. 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 Since 1.2

cairo_status_t cairoLib.Surface.Surface.setUserData ( cairo_user_data_key_t key,
void *  userData,
cairo_destroy_func_t  destroy 
)

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. 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. Returns: CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a slot could not be allocated for the user data.

cairo_status_t cairoLib.Surface.Surface.status (  ) 

Checks whether an error has previously occurred for this surface.

surface: a cairo_surface_t Returns: CAIRO_STATUS_SUCCESS, CAIRO_STATUS_NULL_POINTER, CAIRO_STATUS_NO_MEMORY, CAIRO_STATUS_READ_ERROR, CAIRO_STATUS_INVALID_CONTENT, CAIRO_STATUS_INVALUE_FORMAT, or CAIRO_STATUS_INVALID_VISUAL.


Member Data Documentation

cairo_surface_t* cairoLib.Surface.Surface.cairo_surface [protected]

the main Gtk struct


SourceForge.net Logo DSource.org Logo digitalmars.com Logo