Module org.freedesktop.cairo

Package org.freedesktop.cairo

Class ImageSurface

java.lang.Object

io.github.jwharm.cairobindings.Proxy

org.freedesktop.cairo.Surface

org.freedesktop.cairo.ImageSurface

All Implemented Interfaces:

AutoCloseable

public final class ImageSurface
extends Surface

Image Surfaces — Rendering to memory buffers.

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.

The PNG functions allow reading PNG images into image surfaces, and writing any surface to a PNG file. It is a toy API. It only offers very simple support for reading and writing PNG files, which is sufficient for testing and demonstration purposes. Applications which need more control over the generated PNG file should access the pixel data directly, using getData() or a backend-specific access function, and process it with another library, e.g. gdk-pixbuf or libpng.

Since:

1.0

See Also:

• Surface

Constructor Summary

Constructors

Constructor	Description
ImageSurface(MemorySegment address)	Constructor used internally to instantiate a java ImageSurface object for a native cairo_image_surface_t instance

Method Summary

Modifier and Type	Method	Description
static ImageSurface	create(MemorySegment data, Format format, int width, int height, int stride)	Creates an image surface for the provided pixel data.
static ImageSurface	create(Format format, int width, int height)	Creates an image surface of the specified format and dimensions.
static ImageSurface	createFromPNG(InputStream stream)	Creates a new image surface from PNG data read incrementally from the input stream.
static ImageSurface	createFromPNG(String filename)	Creates a new image surface and initializes the contents to the given PNG file.
static int	formatStrideForWidth(Format format, int width)	This function provides a stride value that will respect all alignment requirements of the accelerated image-rendering code within cairo.
MemorySegment	getData()	Get a pointer to the data of the image surface, for direct inspection or modification.
Format	getFormat()	Get the format of the surface.
int	getHeight()	Get the height of the image surface in pixels.
int	getStride()	Get the stride of the image surface in bytes.
int	getWidth()	Get the width of the image surface in pixels.
void	writeToPNG(OutputStream stream)	Writes the image surface to the output stream.
void	writeToPNG(String filename)	Writes the contents of surface to a new file filename as a PNG image.

Methods inherited from class org.freedesktop.cairo.Surface

close, copyPage, createForRectangle, createSimilar, createSimilarImage, destroy, finish, flush, getContent, getDevice, getDeviceOffset, getDeviceScale, getFallbackResolution, getFontOptions, getMimeData, getSurfaceType, getType, getUserData, hasShowTextGlyphs, mapToImage, markDirty, markDirtyRectangle, setDeviceOffset, setDeviceScale, setFallbackResolution, setMimeData, setUserData, showPage, status, supportsMimeType, unmapImage

Methods inherited from class io.github.jwharm.cairobindings.Proxy

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ImageSurface

public ImageSurface(MemorySegment address)

Constructor used internally to instantiate a java ImageSurface object for a native cairo_image_surface_t instance

Parameters:

address - the memory address of the native cairo_image_surface_t instance

Method Details

formatStrideForWidth

public static int formatStrideForWidth(Format format,
 int width)

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 = ImageSurface.formatStrideForWidth(format, width);
 ImageSurface surface = ImageSurface.createForData(data, format, width, height, stride);
 

Parameters:

format - A Format value

width - The 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

create

public static ImageSurface create(Format format,
 int width,
 int height)

Creates an image surface of the specified format and dimensions. Initially the surface contents are set to 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:

format - format of pixels in the surface to create

width - width of the surface, in pixels

height - height of the surface, in pixels

Returns:

the newly created surface

Since:

1.0

create

public static ImageSurface create(MemorySegment data,
 Format format,
 int width,
 int height,
 int stride)
                           throws IllegalArgumentException

Creates an image surface for the provided pixel data. The output buffer must be kept around until the Surface is destroyed or Surface.finish() is called on the surface. The initial contents of data will be used as the initial image contents; you must explicitly clear the buffer, using, for example, Context.rectangle(double, double, double, double) 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 formatStrideForWidth(Format, int) with the desired format and maximum image width value, and then use the resulting stride value to allocate the data and to create the image surface. See formatStrideForWidth(Format, int) for example code.

Parameters:

data - a 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).

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 as allocated. This value should always be computed by formatStrideForWidth(Format, int) before allocating the data buffer.

Returns:

the newly created surface

Throws:

IllegalArgumentException - in case of invalid stride value

Since:

1.0

createFromPNG

public static ImageSurface createFromPNG(String filename)
                                  throws IOException

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

Parameters:

filename - name of PNG file to load. On Windows this filename is encoded in UTF-8.

Returns:

a new Surface initialized with the contents of the PNG file

Throws:

IOException - when the status of the new Surface is Status.FILE_NOT_FOUND, Status.READ_ERROR or Status.PNG_ERROR.

Since:

1.0

createFromPNG

public static ImageSurface createFromPNG(InputStream stream)
                                  throws IOException

Creates a new image surface from PNG data read incrementally from the input stream.

Parameters:

stream - input stream from which to read the data of the file

Returns:

a new Surface initialized with the contents of the PNG file

Throws:

IOException - if an exception occured while reading from the input stream (Status.READ_ERROR), or libpng returned an error (Status.PNG_ERROR)

Since:

1.0

writeToPNG

public void writeToPNG(String filename)
                throws IOException

Writes the contents of surface to a new file filename as a PNG image.

Parameters:

filename - the name of a file to write to; on Windows this filename is encoded in UTF-8.

Throws:

IOException - if the surface does not have pixel contents (see Status.SURFACE_TYPE_MISMATCH), or an I/O error occurs while attempting to write the file (Status.WRITE_ERROR), or if libpng returned an error (Status.PNG_ERROR).

Since:

1.0

writeToPNG

public void writeToPNG(OutputStream stream)
                throws IOException

Writes the image surface to the output stream.

Parameters:

stream - output stream to write the pixel contents of the surface to

Throws:

IOException - if the surface does not have pixel contents (see Status.SURFACE_TYPE_MISMATCH), or an I/O error occurs while writing to the output stream (Status.WRITE_ERROR), or if libpng returned an error (Status.PNG_ERROR)

Since:

1.0

getData

public MemorySegment getData()

Get a pointer to the data of the image surface, for direct inspection or modification. A call to Surface.flush() is required before accessing the pixel data to ensure that all pending drawing operations are finished. A call to Surface.markDirty() is required after the data is modified.

The size of the returned memory segment is equal to height * stride.

Returns:

a pointer to the image data of this surface or null if surface is not an image surface, or if Surface.finish() has been called.

Since:

1.2

getFormat

public Format getFormat()

Get the format of the surface.

Returns:

the format of the surface

Since:

1.2

getWidth

public int getWidth()

Get the width of the image surface in pixels.

Returns:

the width of the surface in pixels.

Since:

1.0

getHeight

public int getHeight()

Get the height of the image surface in pixels.

Returns:

the height of the surface in pixels.

Since:

1.0

getStride

public int getStride()

Get the stride of the image surface in bytes.

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