An abstract display implementation which handles optimization automatically. More...

Files
file	display-constants.h
	Provides constants related to the abstract display implementation (guac_display).

file	display-types.h
	Provides type definitions related to the abstract display implementation (guac_display).

file	display.h
	Provides an abstract display implementation (guac_display), which handles optimization automatically.

Data Structures
struct	guac_display_layer_cairo_context
	The current Cairo drawing context of a guac_display_layer, including a Cairo image surface wrapping the underlying drawing buffer of the guac_display_layer. More...

struct	guac_display_layer_raw_context
	The current raw drawing context of a guac_display_layer, including the underlying drawing buffer of the guac_display_layer and memory layout information. More...

Macros
#define	GUAC_DISPLAY_MAX_WIDTH 8192
	The maximum width of any guac_display, in pixels.

#define	GUAC_DISPLAY_MAX_HEIGHT 8192
	The maximum height of any guac_display, in pixels.

#define	GUAC_DISPLAY_LAYER_RAW_BPP 4
	The number of bytes in each pixel of raw image data within a guac_display_layer, as made accessible through a call to guac_display_layer_open_raw().

#define	GUAC_DISPLAY_LAYER_RAW_BUFFER(context, rect)
	Returns the memory address of the given rectangle within the image buffer of the given guac_display_layer_raw_context, where the upper-left corner of the given buffer is (0, 0).

Typedefs
typedef struct guac_display	guac_display
	Opaque representation of the remote (client-side) display of a Guacamole connection (guac_client).

typedef struct guac_display_render_thread	guac_display_render_thread
	Opaque representation of a thread that continuously renders updated graphical data to the remote display.

typedef struct guac_display_layer	guac_display_layer
	Opaque representation of a layer within a guac_display.

Enumerations
enum	guac_display_cursor_type { GUAC_DISPLAY_CURSOR_NONE , GUAC_DISPLAY_CURSOR_DOT , GUAC_DISPLAY_CURSOR_IBAR , GUAC_DISPLAY_CURSOR_POINTER }
	Pre-defined mouse cursor graphics. More...

Functions
guac_display *	guac_display_alloc (guac_client *client)
	Allocates a new guac_display representing the remote display shared by all connected users of the given guac_client.

void	guac_display_free (guac_display *display)
	Frees all resources associated with the given guac_display.

void	guac_display_dup (guac_display display, guac_socket socket)
	Replicates the current remote display state across the given socket.

void	guac_display_notify_user_left (guac_display display, guac_user user)
	Notifies the given guac_display that a specific user has left the connection and need no longer be considered for future updates/events.

void	guac_display_notify_user_moved_mouse (guac_display display, guac_user user, int x, int y, int mask)
	Notifies the given guac_display that a specific user has changed the state of the mouse, such as through moving the pointer or pressing/releasing a mouse button.

void	guac_display_end_frame (guac_display *display)
	Ends the current frame, where the number of input frames that were considered in creating this frame is either unknown or inapplicable, allowing the guac_display to complete sending the frame to connected clients.

void	guac_display_end_mouse_frame (guac_display *display)
	Ends the current frame only if the user-visible changes consist purely of updates to the mouse cursor position or icon.

void	guac_display_end_multiple_frames (guac_display *display, int frames)
	Ends the current frame, where that frame may combine or otherwise represent the changes of an arbitrary number of input frames, allowing the guac_display to complete sending the frame to connected clients.

guac_display_layer *	guac_display_default_layer (guac_display *display)
	Returns the default layer for the given display.

guac_display_layer *	guac_display_alloc_layer (guac_display *display, int opaque)
	Allocates a new layer for the given display.

guac_display_layer *	guac_display_alloc_buffer (guac_display *display, int opaque)
	Allocates a new buffer (offscreen layer) for the given display.

void	guac_display_free_layer (guac_display_layer *display_layer)
	Frees the given layer, releasing any underlying memory.

guac_display_layer *	guac_display_cursor (guac_display *display)
	Returns a layer representing the current mouse cursor icon.

void	guac_display_set_cursor (guac_display *display, guac_display_cursor_type cursor_type)
	Sets the remote mouse cursor to the given built-in cursor icon.

void	guac_display_set_cursor_hotspot (guac_display *display, int x, int y)
	Sets the hotspot location of the remote mouse cursor.

void	guac_display_layer_get_bounds (guac_display_layer layer, guac_rect bounds)
	Stores the current bounding rectangle of the given layer in the given guac_rect.

void	guac_display_layer_move (guac_display_layer *layer, int x, int y)
	Moves the given layer to the given coordinates.

void	guac_display_layer_stack (guac_display_layer *layer, int z)
	Sets the stacking position of the given layer relative to all other sibling layers (direct children of the same parent).

void	guac_display_layer_set_parent (guac_display_layer layer, const guac_display_layer parent)
	Reparents the given layer such that it is a direct child of the given parent layer.

void	guac_display_layer_set_opacity (guac_display_layer *layer, int opacity)
	Sets the opacity of the given layer.

void	guac_display_layer_set_lossless (guac_display_layer *layer, int lossless)
	Sets whether graphical changes to the given layer are allowed to be represented, updated, or sent using methods that can cause some loss of information, such as JPEG or WebP compression.

void	guac_display_layer_set_multitouch (guac_display_layer *layer, int touches)
	Sets the level of multitouch support available for the given layer.

void	guac_display_layer_resize (guac_display_layer *layer, int width, int height)
	Resizes the given layer to the given dimensions.

guac_display_layer_raw_context *	guac_display_layer_open_raw (guac_display_layer *layer)
	Begins a drawing operation for the given layer, returning a context that can be used to draw directly to the raw image buffer containing the layer's current pending frame.

void	guac_display_layer_close_raw (guac_display_layer layer, guac_display_layer_raw_context context)
	Ends a drawing operation that was started with a call to guac_display_layer_open_raw() and relinquishes exclusive access to the display.

void	guac_display_layer_raw_context_set (guac_display_layer_raw_context context, const guac_rect dst, uint32_t color)
	Fills a rectangle of image data within the given raw context with a single color.

void	guac_display_layer_raw_context_put (guac_display_layer_raw_context context, const guac_rect dst, const void *restrict buffer, size_t stride)
	Copies a rectangle of image data from the given buffer to the given raw context, replacing all pixel values within the given rectangle.

guac_display_layer_cairo_context *	guac_display_layer_open_cairo (guac_display_layer *layer)
	Begins a drawing operation for the given layer, returning a context that can be used to draw to a Cairo surface containing the layer's current pending frame.

void	guac_display_layer_close_cairo (guac_display_layer layer, guac_display_layer_cairo_context context)
	Ends a drawing operation that was started with a call to guac_display_layer_open_cairo() and relinquishes exclusive access to the display.

guac_display_render_thread *	guac_display_render_thread_create (guac_display *display)
	Creates and starts a rendering thread for the given guac_display.

void	guac_display_render_thread_notify_modified (guac_display_render_thread *render_thread)
	Notifies the given render thread that the graphical state of the display has been modified in some visible way.

void	guac_display_render_thread_notify_frame (guac_display_render_thread *render_thread)
	Notifies the given render thread that a frame boundary has been reached.

void	guac_display_render_thread_destroy (guac_display_render_thread *render_thread)
	Safely stops and frees all resources associated with the given render thread.

Detailed Description

An abstract display implementation which handles optimization automatically.

Current optimizations include:

Scroll/copy detection
Solid color detection
Dirty rectangle reduction
Dynamic selection of PNG/JPEG/WebP compression depending on update content and frequency
Combining/rewriting of updates based on estimated cost

Macro Definition Documentation

◆ GUAC_DISPLAY_LAYER_RAW_BUFFER

#define GUAC_DISPLAY_LAYER_RAW_BUFFER	(		context,
			rect )

Value:

GUAC_RECT_MUTABLE_BUFFER(rect, context->buffer, context->stride, GUAC_DISPLAY_LAYER_RAW_BPP)

GUAC_DISPLAY_LAYER_RAW_BPP

#define GUAC_DISPLAY_LAYER_RAW_BPP

The number of bytes in each pixel of raw image data within a guac_display_layer, as made accessible t...

Definition display-constants.h:50

Returns the memory address of the given rectangle within the image buffer of the given guac_display_layer_raw_context, where the upper-left corner of the given buffer is (0, 0).

If the memory address cannot be calculated because doing so would overflow the maximum value of a size_t, execution of the current process is automatically aborted.

IMPORTANT: No checks are performed on whether the rectangle extends beyond the bounds of the buffer, including considering whether the left/top position of the rectangle is negative. If the rectangle has not already been contrained to be within the bounds of the buffer, such checks must be performed before dereferencing the value returned by this macro.

Parameters

context	The guac_display_layer_raw_context associated with the image buffer within which the address of the given rectangle should be determined.
rect	The rectangle to determine the offset of.

Typedef Documentation

◆ guac_display_layer

typedef struct guac_display_layer guac_display_layer

Opaque representation of a layer within a guac_display.

This may be a visible layer or an off-screen buffer, and is effectively the guac_display equivalent of a guac_layer.

Enumeration Type Documentation

◆ guac_display_cursor_type

enum guac_display_cursor_type

Pre-defined mouse cursor graphics.

Enumerator
GUAC_DISPLAY_CURSOR_NONE	An empty (invisible/hidden) mouse cursor.
GUAC_DISPLAY_CURSOR_DOT	A small dot. This is typically used in situations where cursor information for the remote desktop is not available, thus all cursor rendering must happen remotely, but it's still important that the user be able to see the current location of their local mouse pointer.
GUAC_DISPLAY_CURSOR_IBAR	A vertical, I-shaped bar indicating text input or selection.
GUAC_DISPLAY_CURSOR_POINTER	A standard, general-purpose pointer.

Function Documentation

◆ guac_display_alloc()

guac_display * guac_display_alloc ( guac_client * client )

Allocates a new guac_display representing the remote display shared by all connected users of the given guac_client.

The dimensions of the display should be set with guac_display_default_layer() and guac_display_layer_resize() once the desired display size is known. The guac_display must eventually be freed through a call to guac_display_free().

NOTE: If the buffer of a layer has been replaced with an externally maintained buffer, this function CANNOT be used to resize the layer. The layer must instead be resized through changing the bounds of a guac_display_layer_raw_context and, if necessary, replacing the underlying buffer again.

Parameters

client The guac_client whose remote display should be represented by the new guac_display.

Returns: A newly-allocated guac_display representing the remote display of the given guac_client.

◆ guac_display_alloc_buffer()

guac_display_layer * guac_display_alloc_buffer	(	guac_display *	display,
		int	opaque )

Allocates a new buffer (offscreen layer) for the given display.

When the buffer is no longer needed, it may be freed through calling guac_display_free_layer(). If not freed manually through a call to guac_display_free_layer(), it will be freed when the display is freed with guac_display_free().

Parameters

display	The guac_display to allocate a new buffer for.
opaque	Non-zero if the new buffer will only ever contain opaque image contents (the alpha channel should be ignored), zero otherwise.

Returns: A newly-allocated guac_display_layer representing the new buffer.

◆ guac_display_alloc_layer()

guac_display_layer * guac_display_alloc_layer	(	guac_display *	display,
		int	opaque )

Allocates a new layer for the given display.

The new layer will initially be a direct child of the display's default layer. When the layer is no longer needed, it may be freed through calling guac_display_free_layer(). If not freed manually through a call to guac_display_free_layer(), it will be freed when the display is freed with guac_display_free().

Parameters

display	The guac_display to allocate a new layer for.
opaque	Non-zero if the new layer will only ever contain opaque image contents (the alpha channel should be ignored), zero otherwise.

Returns: A newly-allocated guac_display_layer that is initially a direct child of the default layer.

◆ guac_display_cursor()

guac_display_layer * guac_display_cursor ( guac_display * display )

Returns a layer representing the current mouse cursor icon.

Changes to the contents of this layer will affect the remote mouse cursor after the current pending frame is complete.

Callers should consider using guac_display_end_mouse_frame() to update connected users as soon as all changes to the mouse cursor are completed. Doing so avoids needing to couple changes to the mouse cursor with complicated logic around changes to the remote desktop display.

Parameters

display The guac_display to return the cursor layer for.

Returns: A guac_display_layer representing the mouse cursor of the given guac_display.

◆ guac_display_default_layer()

guac_display_layer * guac_display_default_layer ( guac_display * display )

Returns the default layer for the given display.

The default layer is the only layer that always exists and serves as the root-level layer for all other layers.

See also: GUAC_DEFAULT_LAYER

Parameters

display The guac_display to return the default layer from.

Returns: A guac_display_layer representing the default layer for the given guac_display.

◆ guac_display_dup()

void guac_display_dup	(	guac_display *	display,
		guac_socket *	socket )

Replicates the current remote display state across the given socket.

When new users join a particular guac_client, this function should be used to synchronize those users with the current display state.

Parameters

display	The display that should be synchronized to all users at the other end of the given guac_socket.
socket	The socket to send the current remote display state over.

◆ guac_display_end_frame()

void guac_display_end_frame ( guac_display * display )

Ends the current frame, where the number of input frames that were considered in creating this frame is either unknown or inapplicable, allowing the guac_display to complete sending the frame to connected clients.

Parameters

display The guac_display that should send the current frame.

◆ guac_display_end_mouse_frame()

void guac_display_end_mouse_frame ( guac_display * display )

Ends the current frame only if the user-visible changes consist purely of updates to the mouse cursor position or icon.

If other visible changes have been made, such as graphical updates to the display itself, this function has no effect.

Parameters

display The guac_display that should send the current frame if only the mouse cursor is visibly affected.

◆ guac_display_end_multiple_frames()

void guac_display_end_multiple_frames	(	guac_display *	display,
		int	frames )

Ends the current frame, where that frame may combine or otherwise represent the changes of an arbitrary number of input frames, allowing the guac_display to complete sending the frame to connected clients.

Parameters

display	The guac_display that should send the current frame.
The	number of distinct frames that were considered or combined when generating the current frame, or zero if the boundaries of relevant frames are unknown.

◆ guac_display_free()

void guac_display_free ( guac_display * display )

Frees all resources associated with the given guac_display.

Parameters

display The guac_display to free.

◆ guac_display_free_layer()

void guac_display_free_layer ( guac_display_layer * display_layer )

Frees the given layer, releasing any underlying memory.

If the layer has already been used for rendering, it will be freed on the remote side, as well, when the current pending frame is complete.

Parameters

display_layer The layer to free.

◆ guac_display_layer_close_cairo()

void guac_display_layer_close_cairo	(	guac_display_layer *	layer,
		guac_display_layer_cairo_context *	context )

Ends a drawing operation that was started with a call to guac_display_layer_open_cairo() and relinquishes exclusive access to the display.

All graphical changes made to the layer through the Cairo context will be committed to the layer and will be included in the current pending frame.

This function MUST NOT be called by any thread other than the thread that called guac_display_layer_open_cairo() to obtain the given context.

Parameters

layer	The layer that finished being drawn to.
context	The Cairo context of the drawing operation that has completed, as returned by a previous call to guac_display_layer_open_cairo().

◆ guac_display_layer_close_raw()

void guac_display_layer_close_raw	(	guac_display_layer *	layer,
		guac_display_layer_raw_context *	context )

Ends a drawing operation that was started with a call to guac_display_layer_open_raw() and relinquishes exclusive access to the display.

All graphical changes made to the layer through the raw context will be committed to the layer and will be included in the current pending frame.

This function MUST NOT be called by any thread other than the thread that called guac_display_layer_open_raw() to obtain the given context.

Parameters

layer	The layer that finished being drawn to.
context	The raw context of the drawing operation that has completed, as returned by a previous call to guac_display_layer_open_raw().

◆ guac_display_layer_get_bounds()

void guac_display_layer_get_bounds	(	guac_display_layer *	layer,
		guac_rect *	bounds )

Stores the current bounding rectangle of the given layer in the given guac_rect.

The boundary stored will be the boundary of the current pending frame.

@oaram layer The layer to determine the dimensions of.

Parameters

bounds The guac_rect that should receive the bounding rectangle of the given layer.

◆ guac_display_layer_move()

void guac_display_layer_move	(	guac_display_layer *	layer,
		int	x,
		int	y )

Moves the given layer to the given coordinates.

The changes to the given layer will be made as part of the current pending frame, and will not take effect on remote displays until the pending frame is complete.

Parameters

layer	The layer to set the position of.
x	The X coordinate of the upper-left corner of the layer, in pixels.
y	The Y coordinate of the upper-left corner of the layer, in pixels.

◆ guac_display_layer_open_cairo()

guac_display_layer_cairo_context * guac_display_layer_open_cairo ( guac_display_layer * layer )

Begins a drawing operation for the given layer, returning a context that can be used to draw to a Cairo surface containing the layer's current pending frame.

The underlying Cairo state within the returned context will be preserved between calls to guac_display_layer_open_cairo().

Starting a draw operation acquires exclusive access to the display for the current thread. When complete, the original calling thread must relinquish exclusive access and free the graphical context by calling guac_display_layer_close_cairo(). It is the responsibility of the caller to ensure the dirty rect within the returned context is updated to contain the region modified, such as by calling guac_rect_expand().

Parameters

layer The layer to draw to.

Returns: A mutable graphical context containing the current pending frame state of the given layer in the form of a Cairo surface.

◆ guac_display_layer_open_raw()

guac_display_layer_raw_context * guac_display_layer_open_raw ( guac_display_layer * layer )

Begins a drawing operation for the given layer, returning a context that can be used to draw directly to the raw image buffer containing the layer's current pending frame.

Starting a draw operation acquires exclusive access to the display for the current thread. When complete, the original calling thread must relinquish exclusive access and free the graphical context by calling guac_display_layer_close_raw(). It is the responsibility of the caller to ensure the dirty rect within the returned context is updated to contain the region modified, such as by calling guac_rect_expand().

Parameters

layer The layer to draw to.

Returns: A mutable graphical context containing the current raw pending frame state of the given layer.

◆ guac_display_layer_raw_context_put()

void guac_display_layer_raw_context_put	(	guac_display_layer_raw_context *	context,
		const guac_rect *	dst,
		const void *restrict	buffer,
		size_t	stride )

Copies a rectangle of image data from the given buffer to the given raw context, replacing all pixel values within the given rectangle.

Compositing is not performed by this function.

The size of the image data copied and the destination location of that data within the layer are dictated by the given rectangle. If any offset needs to be applied to the source image buffer, it is expected that this offset will already have been applied via the address of the buffer provided to this function, such as through an earlier call to GUAC_RECT_CONST_BUFFER().

Parameters

context	The raw context of the layer that is being drawn to.
dst	The rectangular area that should be filled with the image data from the given buffer.
buffer	The containing the image data that should replace all current pixel values within the given rectangular region.
stride	The number of bytes in each row of image data within the given buffer.

◆ guac_display_layer_raw_context_set()

void guac_display_layer_raw_context_set	(	guac_display_layer_raw_context *	context,
		const guac_rect *	dst,
		uint32_t	color )

Fills a rectangle of image data within the given raw context with a single color.

All pixels within the rectangle are replaced with the given color. If applicable, this includes the alpha channel. Compositing is not performed by this function.

Parameters

context	The raw context of the layer that is being drawn to.
dst	The rectangular area that should be filled with the given color.
color	The color that should replace all current pixel values within the given rectangular region.

◆ guac_display_layer_resize()

void guac_display_layer_resize	(	guac_display_layer *	layer,
		int	width,
		int	height )

Resizes the given layer to the given dimensions.

The change in layer size will be made as part of the current pending frame, and will not take effect on remote displays until the pending frame is complete.

This function will not resize the underlying buffer containing image data if the layer has been manually reassociated with a different, externally-maintained buffer using a guac_display_layer_raw_context. If this is the case, that buffer must instead be manually maintained by the caller, and resizing will typically involve replacing the buffer again.

IMPORTANT: While it is safe to call this function while holding an open context (raw or Cairo), this should only be done if the underlying buffer is maintained externally or if the context is finished being used. Resizing a layer can result in the underlying buffer being replaced.

Parameters

layer	The layer to set the size of.
width	The new width to assign to the layer, in pixels. Any values provided that are greater than GUAC_DISPLAY_MAX_WIDTH will instead be interpreted as equal to GUAC_DISPLAY_MAX_WIDTH.
height	The new height to assign to the layer, in pixels. Any values provided that are greater than GUAC_DISPLAY_MAX_HEIGHT will instead be interpreted as equal to GUAC_DISPLAY_MAX_HEIGHT.

◆ guac_display_layer_set_lossless()

void guac_display_layer_set_lossless	(	guac_display_layer *	layer,
		int	lossless )

Sets whether graphical changes to the given layer are allowed to be represented, updated, or sent using methods that can cause some loss of information, such as JPEG or WebP compression.

By default, layers are allowed to use lossy methods. Changes to lossy vs. lossless behavior will affect the current pending frame, as well as any frames that follow.

Parameters

layer	The layer to change the lossy behavior of.
lossless	Non-zero if the layer should be allowed to use lossy methods (the default behavior), zero if the layer should use strictly lossless methods.

◆ guac_display_layer_set_multitouch()

void guac_display_layer_set_multitouch	(	guac_display_layer *	layer,
		int	touches )

Sets the level of multitouch support available for the given layer.

The change in layer multitouch support will be made as part of the current pending frame, and will not take effect on remote displays until the pending frame is complete. Setting multitouch support only has any effect on the default layer.

Parameters

layer	The layer to set the multitouch support level of.
touches	The maximum number of simultaneous touches tracked by the layer, where 0 represents no touch support.

◆ guac_display_layer_set_opacity()

void guac_display_layer_set_opacity	(	guac_display_layer *	layer,
		int	opacity )

Sets the opacity of the given layer.

The change in layer opacity will be made as part of the current pending frame, and will not take effect on remote displays until the pending frame is complete.

Parameters

layer	The layer to change the opacity of.
opacity	The opacity to assign to the given layer, as a value between 0 and 255 inclusive, where 0 is completely transparent and 255 is completely opaque.

◆ guac_display_layer_set_parent()

void guac_display_layer_set_parent	(	guac_display_layer *	layer,
		const guac_display_layer *	parent )

Reparents the given layer such that it is a direct child of the given parent layer.

The change in layer hierarchy will be made as part of the current pending frame, and will not take effect on remote displays until the pending frame is complete.

Parameters

layer	The layer to change the parent of.
parent	The layer that should be the new parent.

◆ guac_display_layer_stack()

void guac_display_layer_stack	(	guac_display_layer *	layer,
		int	z )

Sets the stacking position of the given layer relative to all other sibling layers (direct children of the same parent).

The change in relative layer stacking position will be made as part of the current pending frame, and will not take effect on remote displays until the pending frame is complete.

Parameters

layer	The layer to set the stacking position of.
z	The relative order of this layer.

◆ guac_display_notify_user_left()

void guac_display_notify_user_left	(	guac_display *	display,
		guac_user *	user )

Notifies the given guac_display that a specific user has left the connection and need no longer be considered for future updates/events.

This SHOULD always be called when a user leaves the connection to ensure other future, user-related events are interpreted correctly.

Parameters

display	The guac_display to notify.
user	The user that left the connection.

◆ guac_display_notify_user_moved_mouse()

void guac_display_notify_user_moved_mouse	(	guac_display *	display,
		guac_user *	user,
		int	x,
		int	y,
		int	mask )

Notifies the given guac_display that a specific user has changed the state of the mouse, such as through moving the pointer or pressing/releasing a mouse button.

This function automatically invokes guac_display_end_mouse_frame().

Parameters

display	The guac_display to notify.
user	The user that moved the mouse or pressed/released a mouse button.
x	The X position of the mouse, in pixels.
y	The Y position of the mouse, in pixels.
mask	An integer value representing the current state of each button, where the Nth bit within the integer is set to 1 if and only if the Nth mouse button is currently pressed. The lowest-order bit is the left mouse button, followed by the middle button, right button, and finally the up and down buttons of the scroll wheel.

See also: GUAC_CLIENT_MOUSE_LEFT; GUAC_CLIENT_MOUSE_MIDDLE; GUAC_CLIENT_MOUSE_RIGHT; GUAC_CLIENT_MOUSE_SCROLL_UP; GUAC_CLIENT_MOUSE_SCROLL_DOWN

◆ guac_display_render_thread_create()

guac_display_render_thread * guac_display_render_thread_create ( guac_display * display )

Creates and starts a rendering thread for the given guac_display.

The returned thread must eventually be freed with a call to guac_display_render_thread_destroy(). The rendering thread simplifies efficient handling of guac_display, but is not a requirement. If your use case is not well-served by the provided render thread, you can use your own render loop, thread, etc.

The render thread will finalize and send frames after being notified that graphical changes have occurred, heuristically determining frame boundaries based on the lull in modifications that occurs between frames. In the event that modifications are made continuously without pause, the render thread will finalize and send frames at a reasonable minimum rate.

If explicit frame boundaries are available, the render thread can be notified of these boundaries. Explicit boundaries will be preferred by the render thread over heuristically determined boundaries.

See also: guac_display_render_thread_notify_modified(); guac_display_render_thread_notify_frame()

Parameters

display The display to start a rendering thread for.

Returns: An opaque reference to the created, running rendering thread. This thread must be eventually freed through a call to guac_display_render_thread_destroy().

◆ guac_display_render_thread_destroy()

void guac_display_render_thread_destroy ( guac_display_render_thread * render_thread )

Safely stops and frees all resources associated with the given render thread.

The provided pointer to the render thread is no longer valid after a call to this function. The guac_display associated with the render thread is unaffected.

Parameters

render_thread The render thread to stop and free.

◆ guac_display_render_thread_notify_frame()

void guac_display_render_thread_notify_frame ( guac_display_render_thread * render_thread )

Notifies the given render thread that a frame boundary has been reached.

Further heuristic detection of frame boundaries by the render thread will stop, and all further frames must be marked through calls to this function.

Parameters

render_thread The render thread to notify of an explicit frame boundary.

◆ guac_display_render_thread_notify_modified()

void guac_display_render_thread_notify_modified ( guac_display_render_thread * render_thread )

Notifies the given render thread that the graphical state of the display has been modified in some visible way.

The changes will then be included in a future frame by the render thread once a frame boundary has been reached. If frame boundaries are currently being determined heuristically by the render thread, it is the timing of calls to this function that determine the boundaries of frames.

Parameters

render_thread The render thread to notify of display modifications.

◆ guac_display_set_cursor()

void guac_display_set_cursor	(	guac_display *	display,
		guac_display_cursor_type	cursor_type )

Sets the remote mouse cursor to the given built-in cursor icon.

This function automatically invokes guac_display_end_mouse_frame().

Callers should consider using guac_display_end_mouse_frame() to update connected users as soon as all changes to the mouse cursor are completed. Doing so avoids needing to couple changes to the mouse cursor with complicated logic around changes to the remote desktop display.

Parameters

display	The guac_display to set the cursor of.
cursor_type	The built-in cursor icon to set the remote cursor to.

◆ guac_display_set_cursor_hotspot()

void guac_display_set_cursor_hotspot	(	guac_display *	display,
		int	x,
		int	y )

Sets the hotspot location of the remote mouse cursor.

The hotspot is the point within the mouse cursor where the click occurs. Changes to the hotspot of the remote mouse cursor will take effect after the current pending frame is complete.

Callers should consider using guac_display_end_mouse_frame() to update connected users as soon as all changes to the mouse cursor are completed. Doing so avoids needing to couple changes to the mouse cursor with complicated logic around changes to the remote desktop display.

Parameters

display	The guac_display to set the cursor hotspot of.
x	The X coordinate of the cursor hotspot, in pixels.
y	The Y coordinate of the cursor hotspot, in pixels.

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ GUAC_DISPLAY_LAYER_RAW_BUFFER

Typedef Documentation

◆ guac_display_layer

Enumeration Type Documentation

◆ guac_display_cursor_type

Function Documentation

◆ guac_display_alloc()

◆ guac_display_alloc_buffer()

◆ guac_display_alloc_layer()

◆ guac_display_cursor()

◆ guac_display_default_layer()

◆ guac_display_dup()

◆ guac_display_end_frame()

◆ guac_display_end_mouse_frame()

◆ guac_display_end_multiple_frames()

◆ guac_display_free()

◆ guac_display_free_layer()

◆ guac_display_layer_close_cairo()

◆ guac_display_layer_close_raw()

◆ guac_display_layer_get_bounds()

◆ guac_display_layer_move()

◆ guac_display_layer_open_cairo()

◆ guac_display_layer_open_raw()

◆ guac_display_layer_raw_context_put()

◆ guac_display_layer_raw_context_set()

◆ guac_display_layer_resize()

◆ guac_display_layer_set_lossless()

◆ guac_display_layer_set_multitouch()

◆ guac_display_layer_set_opacity()

◆ guac_display_layer_set_parent()

◆ guac_display_layer_stack()

◆ guac_display_notify_user_left()

◆ guac_display_notify_user_moved_mouse()

◆ guac_display_render_thread_create()

◆ guac_display_render_thread_destroy()

◆ guac_display_render_thread_notify_frame()

◆ guac_display_render_thread_notify_modified()

◆ guac_display_set_cursor()

◆ guac_display_set_cursor_hotspot()