Module org.freedesktop.cairo

Package org.freedesktop.cairo

Class Device

java.lang.Object

io.github.jwharm.cairobindings.Proxy

org.freedesktop.cairo.Device

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

Script

public class Device
extends Proxy
implements AutoCloseable

Devices are the abstraction Cairo employs for the rendering system used by a Surface. You can get the device of a surface using Surface.getDevice().

Devices are created using custom functions specific to the rendering system you want to use. See the documentation for the surface types for those functions.

An important function that devices fulfill is sharing access to the rendering system between Cairo and your application. If you want to access a device directly that you used to draw to with Cairo, you must first call flush() to ensure that Cairo finishes all operations on the device and resets it to a clean state.

Cairo also provides the functions acquire() and release() to synchronize access to the rendering system in a multithreaded environment. This is done internally, but can also be used by applications.

Please refer to the documentation of each backend for additional usage requirements, guarantees provided, and interactions with existing surface API of the device functions for surfaces of that type.

Since:

1.10

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
void	acquire()	Acquires the device for the current thread.
void	close()	Closing a device will invoke finish(), which will flush the device and drop all references to external resources.
void	destroy()	Invokes the cleanup action that is normally invoked during garbage collection.
void	finish()	This function finishes the device and drops all references to external resources.
void	flush()	Finish any pending operations for the device and also restore any temporary modifications cairo has made to the device's state.
DeviceType	getDeviceType()	This function returns the type of the device.
static org.gnome.glib.Type	getType()	Get the CairoDevice GType
MemorySegment	getUserData(UserDataKey key)	Return user data previously attached to the device using the specified key.
double	observerElapsed()	Returns the total elapsed time of the observation.
double	observerFillElapsed()	Returns the elapsed time of the fill operations.
double	observerGlyphsElapsed()	Returns the elapsed time of the glyph operations.
double	observerMaskElapsed()	Returns the elapsed time of the mask operations.
double	observerPaintElapsed()	Returns the elapsed time of the paint operations.
void	observerPrint(OutputStream stream)	Prints the device log using the given OutputStream.
double	observerStrokeElapsed()	Returns the elapsed time of the stroke operations.
void	release()	Releases a device previously acquired using acquire().
UserDataKey	setUserData(UserDataKey key, MemorySegment userData)	Attach user data to the device.
Status	status()	Checks whether an error has previously occurred for this device.

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

Device

public Device(MemorySegment address)

Constructor used internally to instantiate a java Device object for a native cairo_device_t instance

Parameters:

address - the memory address of the native cairo_device_t instance

Method Details

destroy

public void destroy()

Invokes the cleanup action that is normally invoked during garbage collection. If the instance is "owned" by the user, the destroy() function is run to dispose the native instance.

status

public Status status()

Checks whether an error has previously occurred for this device.

Returns:

Status.SUCCESS on success or an error code if the device is in an error state.

Since:

1.10

finish

public void finish()

This function finishes the device and drops all references to external resources. All surfaces, fonts and other objects created for this device will be finished, too. Further operations on the device will not affect the device but will instead trigger a Status.DEVICE_FINISHED error.

When the last call to destroy() decreases the reference count to zero, cairo will call finish() if it hasn't been called already, before freeing the resources associated with the device.

This function may acquire devices.

Since:

1.10

flush

public void flush()

Finish any pending operations for the device and also restore any temporary modifications cairo has made to the device's state. This function must be called before switching from using the device with Cairo to operating on it directly with native APIs. If the device doesn't support direct access, then this function does nothing.

This function may acquire devices.

Since:

1.10

getDeviceType

public DeviceType getDeviceType()

This function returns the type of the device. See DeviceType for available types.

Returns:

the type of the device

Since:

1.10

acquire

public void acquire()
             throws IllegalStateException

Acquires the device for the current thread. This function will block until no other thread has acquired the device. From then on, your thread owns the device and no other thread will be able to acquire it until a matching call to release(). It is allowed to recursively acquire the device multiple times from the same thread.

You must never acquire two different devices at the same time unless this is explicitly allowed. Otherwise the possibility of deadlocks exist. As various Cairo functions can acquire devices when called, these functions may also cause deadlocks when you call them with an acquired device. So you must not have a device acquired when calling them. These functions are marked in the documentation.

After a successful call to acquire(), a matching call to release() is required.

Throws:

IllegalStateException - if the device is in an error state and could not be acquired.

Since:

1.10

release

public void release()

Releases a device previously acquired using acquire(). See that function for details.

Since:

1.10

observerElapsed

public double observerElapsed()

Returns the total elapsed time of the observation.

Returns:

the elapsed time, in nanoseconds.

Since:

1.12

observerFillElapsed

public double observerFillElapsed()

Returns the elapsed time of the fill operations.

Returns:

the elapsed time, in nanoseconds.

Since:

1.12

observerGlyphsElapsed

public double observerGlyphsElapsed()

Returns the elapsed time of the glyph operations.

Returns:

the elapsed time, in nanoseconds.

Since:

1.12

observerMaskElapsed

public double observerMaskElapsed()

Returns the elapsed time of the mask operations.

Returns:

the elapsed time, in nanoseconds

Since:

1.12

observerPaintElapsed

public double observerPaintElapsed()

Returns the elapsed time of the paint operations.

Returns:

the elapsed time, in nanoseconds

Since:

1.12

observerPrint

public void observerPrint(OutputStream stream)
                   throws IOException

Prints the device log using the given OutputStream.

Parameters:

stream - the OutputStream

Throws:

IOException - an unexpected error occured whil printing the device log

Since:

1.12

observerStrokeElapsed

public double observerStrokeElapsed()

Returns the elapsed time of the stroke operations.

Returns:

the elapsed time, in nanoseconds.

Since:

1.12

setUserData

public UserDataKey setUserData(UserDataKey key,
 MemorySegment userData)

Attach user data to the device. To remove user data from a device, call this function with the key that was used to set it and null for userData.

Parameters:

key - the key to attach the user data to

userData - the user data to attach to the device

Returns:

the key

Throws:

NullPointerException - if key is null

Since:

1.4

getUserData

public MemorySegment getUserData(UserDataKey key)

Return user data previously attached to the device using the specified key. If no user data has been attached with the given key this function returns null.

The returned memory segment has zero length. It can be resized with MemorySegment.reinterpret(long)^RESTRICTED.

Parameters:

key - the UserDataKey the user data was attached to

Returns:

the user data previously attached or null

Since:

1.4

close

public void close()

Closing a device will invoke finish(), which will flush the device and drop all references to external resources. A closed device cannot be used to perform drawing operations and cannot be reopened.

Although the Java bindings make an effort to properly dispose native resources using a Cleaner, this is not guaranteed to work in all situations. Users must therefore always call close() or finish() on devices (either manually or with a try-with-resources statement) or risk issues like resource exhaustion and data loss.

Specified by:

close in interface AutoCloseable

getType

public static org.gnome.glib.Type getType()

Get the CairoDevice GType

Returns:

the GType