cairomm 1.18.0
Public Member Functions | Static Public Member Functions | List of all members
Cairo::ImageSurface Class Reference

Image surfaces provide the ability to render to memory buffers either allocated by cairo or by the calling code. More...

#include <cairomm/surface.h>

Inheritance diagram for Cairo::ImageSurface:
Inheritance graph
[legend]

Public Member Functions

 ImageSurface (cairo_surface_t *cobject, bool has_reference=false)
 Create a C++ wrapper for the C instance. More...
 
 ~ImageSurface () override
 
int get_width () const
 Gets the width of the ImageSurface in pixels. More...
 
int get_height () const
 Gets the height of the ImageSurface in pixels. More...
 
Format get_format () const
 Gets the format of the surface. More...
 
int get_stride () const
 Returns the stride of the image surface in bytes (or 0 if surface is not an image surface). More...
 
unsigned char * get_data ()
 Get a pointer to the data of the image surface, for direct inspection or modification. More...
 
const unsigned char * get_data () const
 
- Public Member Functions inherited from Cairo::Surface
 Surface (cairo_surface_t *cobject, bool has_reference=false)
 Create a C++ wrapper for the C instance. More...
 
 Surface (const Surface &)=delete
 
Surfaceoperator= (const Surface &)=delete
 
virtual ~Surface ()
 
const unsigned char * get_mime_data (const std::string & mime_type, unsigned long & length)
 Return mime data previously attached to surface using the specified mime type. More...
 
void set_mime_data (const std::string & mime_type, unsigned char *data, unsigned long length, const SlotDestroy & slot_destroy)
 Attach an image in the format mime_type to surface. More...
 
void unset_mime_data (const std::string & mime_type)
 Remove the data from a surface. More...
 
void get_font_options (FontOptions & options) const
 Retrieves the default font rendering options for the surface. More...
 
void finish ()
 This function finishes the surface and drops all references to external resources. More...
 
void flush ()
 Do any pending drawing for the surface and also restore any temporary modifications cairo has made to the surface's state. More...
 
void mark_dirty ()
 Tells cairo to consider the data buffer dirty. More...
 
void mark_dirty (int x, int y, int width, int height)
 Marks a rectangular area of the given surface dirty. More...
 
void set_device_offset (double x_offset, double y_offset)
 Sets an offset that is added to the device coordinates determined by the CTM when drawing to surface. More...
 
void get_device_offset (double & x_offset, double & y_offset) const
 Returns a previous device offset set by set_device_offset(). More...
 
void set_device_scale (double x_scale, double y_scale)
 Sets a scale that is multiplied to the device coordinates determined by the CTM when drawing to surface. More...
 
void set_device_scale (double scale)
 Sets x and y scale to the same value. More...
 
void get_device_scale (double & x_scale, double & y_scale) const
 Returns a previous device scale set by set_device_scale(). More...
 
double get_device_scale () const
 Returns the x and y average of a previous device scale set by set_device_scale(). More...
 
void set_fallback_resolution (double x_pixels_per_inch, double y_pixels_per_inch)
 Set the horizontal and vertical resolution for image fallbacks. More...
 
void get_fallback_resolution (double & x_pixels_per_inch, double & y_pixels_per_inch) const
 This function returns the previous fallback resolution set by set_fallback_resolution(), or default fallback resolution if never set. More...
 
Type get_type () const
 
Content get_content () const
 This function returns the content type of surface which indicates whether the surface contains color and/or alpha information. More...
 
void copy_page ()
 Emits the current page for backends that support multiple pages, but doesn't clear it, so that the contents of the current page will be retained for the next page. More...
 
void show_page ()
 Emits and clears the current page for backends that support multiple pages. More...
 
bool has_show_text_glyphs () const
 Returns whether the surface supports sophisticated Context::show_text_glyphs() operations. More...
 
void write_to_png (const std::string & filename)
 Writes the contents of surface to a new file filename as a PNG image. More...
 
void write_to_png_stream (const SlotWriteFunc & write_func)
 Writes the Surface to the write function. More...
 
RefPtr< Deviceget_device ()
 This function returns the device for a surface. More...
 
cobjectcobj ()
 Provides acces to the underlying C cairo surface. More...
 
const cobjectcobj () const
 Provides acces to the underlying C cairo surface. More...
 

Static Public Member Functions

static int format_stride_for_width (Format format, int width)
 This function provides a stride value that will respect all alignment requirements of the accelerated image-rendering code within cairo. More...
 
static RefPtr< ImageSurfacecreate (Format format, int width, int height)
 Creates an image surface of the specified format and dimensions. More...
 
static RefPtr< ImageSurfacecreate (unsigned char *data, Format format, int width, int height, int stride)
 Creates an image surface for the provided pixel data. More...
 
static RefPtr< ImageSurfacecreate_from_png (std::string filename)
 Creates a new image surface and initializes the contents to the given PNG file. More...
 
static RefPtr< ImageSurfacecreate_from_png_stream (const SlotReadFunc & read_func)
 Creates a new image surface from PNG data read incrementally via the read_func function. More...
 
- Static Public Member Functions inherited from Cairo::Surface
static RefPtr< Surfacecreate (const RefPtr< Surface > other, Content content, int width, int height)
 Create a new surface that is as compatible as possible with an existing surface. More...
 
static RefPtr< Surfacecreate (const RefPtr< Surface > & target, double x, double y, double width, double height)
 Create a new surface that is a rectangle within the target surface. More...
 

Additional Inherited Members

- Public Types inherited from Cairo::Surface
enum class  Type {
  IMAGE = CAIRO_SURFACE_TYPE_IMAGE ,
  PDF = CAIRO_SURFACE_TYPE_PDF ,
  PS = CAIRO_SURFACE_TYPE_PS ,
  XLIB = CAIRO_SURFACE_TYPE_XLIB ,
  XCB = CAIRO_SURFACE_TYPE_XCB ,
  GLITZ = CAIRO_SURFACE_TYPE_GLITZ ,
  QUARTZ = CAIRO_SURFACE_TYPE_QUARTZ ,
  WIN32 = CAIRO_SURFACE_TYPE_WIN32 ,
  WIN32_SURFACE = CAIRO_SURFACE_TYPE_WIN32 ,
  BEOS = CAIRO_SURFACE_TYPE_BEOS ,
  DIRECTFB = CAIRO_SURFACE_TYPE_DIRECTFB ,
  SVG = CAIRO_SURFACE_TYPE_SVG ,
  OS2 = CAIRO_SURFACE_TYPE_OS2 ,
  WIN32_PRINTING = CAIRO_SURFACE_TYPE_WIN32_PRINTING ,
  QUARTZ_IMAGE = CAIRO_SURFACE_TYPE_QUARTZ_IMAGE ,
  SCRIPT = CAIRO_SURFACE_TYPE_SCRIPT ,
  QT = CAIRO_SURFACE_TYPE_QT ,
  RECORDING = CAIRO_SURFACE_TYPE_RECORDING ,
  VG = CAIRO_SURFACE_TYPE_VG ,
  GL = CAIRO_SURFACE_TYPE_GL ,
  DRM = CAIRO_SURFACE_TYPE_DRM ,
  TEE = CAIRO_SURFACE_TYPE_TEE ,
  XML = CAIRO_SURFACE_TYPE_XML ,
  SKIA = CAIRO_SURFACE_TYPE_SKIA ,
  SUBSURFACE = CAIRO_SURFACE_TYPE_SUBSURFACE
}
 Cairo::Surface::Type is used to describe the type of a given surface. More...
 
enum class  Format {
  ARGB32 = CAIRO_FORMAT_ARGB32 ,
  RGB24 = CAIRO_FORMAT_RGB24 ,
  A8 = CAIRO_FORMAT_A8 ,
  A1 = CAIRO_FORMAT_A1 ,
  RGB16_565 = CAIRO_FORMAT_RGB16_565
}
 Cairo::Surface::Format is used to identify the memory format of image data. More...
 
typedef sigc::slot< ErrorStatus(const unsigned char *, unsigned int)> SlotWriteFunc
 For example: ErrorStatus my_write_func(unsigned char* data, unsigned int length); More...
 
typedef sigc::slot< ErrorStatus(unsigned char *, unsigned int)> SlotReadFunc
 This is the type of function which is called when a backend needs to read data from an input stream. More...
 
typedef sigc::slot< void()> SlotDestroy
 For instance, void on_destroy();. More...
 
typedef cairo_surface_t cobject
 The underlying C cairo surface type. More...
 
- Protected Attributes inherited from Cairo::Surface
cobjectm_cobject
 The underlying C cairo surface type that is wrapped by this Surface. More...
 

Detailed Description

Image surfaces provide the ability to render to memory buffers either allocated by cairo or by the calling code.

The supported image formats are those defined in Format

An ImageSurface is the most generic type of Surface and the only one that is available by default. You can either create an ImageSurface whose data is managed by Cairo, or you can create an ImageSurface with a data buffer that you allocated yourself so that you can have full access to the data.

When you create an ImageSurface with your own data buffer, you are free to examine the results at any point and do whatever you want with it. Note that if you modify anything and later want to continue to draw to the surface with cairo, you must let cairo know via Cairo::Surface::mark_dirty()

Note that like all surfaces, an ImageSurface is a reference-counted object that should be used via Cairo::RefPtr.

Constructor & Destructor Documentation

◆ ImageSurface()

Cairo::ImageSurface::ImageSurface ( cairo_surface_t *  cobject,
bool  has_reference = false 
)
explicit

Create a C++ wrapper for the C instance.

This C++ instance should then be given to a RefPtr.

Parameters
cobjectThe C instance.
has_referenceWhether we already have a reference. Otherwise, the constructor will take an extra reference.

◆ ~ImageSurface()

Cairo::ImageSurface::~ImageSurface ( )
override

Member Function Documentation

◆ create() [1/2]

static RefPtr< ImageSurface > Cairo::ImageSurface::create ( Format  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).

Parameters
formatformat of pixels in the surface to create
widthwidth of the surface, in pixels
heightheight of the surface, in pixels
Returns
a RefPtr to the newly created surface.
Examples
image-surface.cc, toy-text.cc, and user-font.cc.

◆ create() [2/2]

static RefPtr< ImageSurface > Cairo::ImageSurface::create ( unsigned char *  data,
Format  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 surface is destroyed or finish() is called on the surface. The initial contents of buffer will be used as the initial image contents; you must explicitly clear the buffer, using, for example, Context::rectangle() and Context::fill() if you want it cleared.

Note that the stride may be larger than width * bytes_per_pixel to provide proper alignment for each pixel and row. This alignment is required to allow high-performance rendering within cairo. The correct way to obtain a legal stride value is to call format_stride_for_width() with the desired format and maximum image width value, and the use the resulting stride value to allocate the data and to create the image surface. See format_stride_for_width() for example code.

Parameters
dataa pointer to a buffer supplied by the application in which to write contents. This pointer must be suitably aligned for any kind of variable, (for example, a pointer returned by malloc).
formatthe format of pixels in the buffer
widththe width of the image to be stored in the buffer
heightthe height of the image to be stored in the buffer
stridethe number of bytes between the start of rows in the buffer as allocated. This value should always be computed by format_stride_for_width() before allocating the data buffer.
Returns
a RefPtr to the newly created surface.

◆ create_from_png()

static RefPtr< ImageSurface > Cairo::ImageSurface::create_from_png ( std::string  filename)
static

Creates a new image surface and initializes the contents to the given PNG file.

Note
For this function to be available, cairo must have been compiled with PNG support.
Parameters
filenamename of PNG file to load
Returns
a RefPtr to the new cairo_surface_t initialized with the contents of the PNG image file.

◆ create_from_png_stream()

static RefPtr< ImageSurface > Cairo::ImageSurface::create_from_png_stream ( const SlotReadFunc read_func)
static

Creates a new image surface from PNG data read incrementally via the read_func function.

Note
For this function to be available, cairo must have been compiled with PNG support.
Parameters
read_funcfunction called to read the data of the file
Returns
a RefPtr to the new cairo_surface_t initialized with the contents of the PNG image file.

◆ format_stride_for_width()

static int Cairo::ImageSurface::format_stride_for_width ( Format  format,
int  width 
)
static

This function provides a stride value that will respect all alignment requirements of the accelerated image-rendering code within cairo.

Typical usage will be of the form:

int stride;
unsigned char *data;
data = malloc (stride * height);
surface = Cairo::ImageSurface::create (data, format, width, height);
valarray< size_t > stride() const
constexpr auto data(_Container &__cont) noexcept(noexcept(__cont.data())) -> decltype(__cont.data())
static RefPtr< ImageSurface > create(Format format, int width, int height)
Creates an image surface of the specified format and dimensions.
static int format_stride_for_width(Format format, int width)
This function provides a stride value that will respect all alignment requirements of the accelerated...
Parameters
formatA Format value
widthThe desired width of an image surface to be created.
Returns
the appropriate stride to use given the desired format and width, or -1 if either the format is invalid or the width too large.
Since
1.6

◆ get_data() [1/2]

unsigned char * Cairo::ImageSurface::get_data ( )

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

Return value: a pointer to the image data of this surface or NULL if @surface is not an image surface.

Since
1.2

◆ get_data() [2/2]

const unsigned char * Cairo::ImageSurface::get_data ( ) const

◆ get_format()

Format Cairo::ImageSurface::get_format ( ) const

Gets the format of the surface.

Since
1.2

◆ get_height()

int Cairo::ImageSurface::get_height ( ) const

Gets the height of the ImageSurface in pixels.

◆ get_stride()

int Cairo::ImageSurface::get_stride ( ) const

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

◆ get_width()

int Cairo::ImageSurface::get_width ( ) const

Gets the width of the ImageSurface in pixels.


The documentation for this class was generated from the following file: