#include <LCursor.h>

Utility class for rendering cursors. More...

Detailed Description

Utility class for rendering cursors.

The LCursor class is designed to make cursor rendering easier and take advantage of compositing properties of certain graphic backends to improve performance.

Hardware Composition

Some graphic backends, such as DRM, allow for hardware cursor compositing, which can improve performance by reducing the need to repaint an output every time the cursor changes position.
To check if an output supports hardware cursor compositing, use the hasHardwareSupport() method.
If hardware compositing is not supported, the cursor needs to be rendered using OpenGL. In that case, the cursor's position (with the hotspot offset included) and size can be accessed using the rect() method, and its current texture with the texture() method.

Smoother Hardware Cursor Updates

By default, the DRM graphic backend uses the Atomic DRM API, which synchronizes hardware cursor updates with the refresh rate of the outputs. However, this synchronization can result in laggy cursor updates when rendering take a long time. On the other hand, the legacy DRM API supports asynchronous hardware cursor updates, which can provide a smoother cursor experience. To switch to the legacy DRM API, set the SRM_FORCE_LEGACY_API environment variable to 1.

Warning: Please note that using the legacy DRM API may cause issues with certain proprietary Nvidia drivers.

Public Member Functions
void	useDefault ()
	Load the default cursor. More...

void	replaceDefaultB (const LTexture *texture, const LPointF &hotspot)
	Replace Louvre's default cursor. More...

void	setTextureB (const LTexture *texture, const LPointF &hotspot)
	Set the cursor texture. More...

LTexture *	texture () const
	Get the current cursor texture. More...

LTexture *	defaultTexture () const
	Get the default cursor texture. More...

const LPointF &	defaultHotspotB () const
	Get the default cursor hotspot. More...

LTexture *	defaultLouvreTexture () const
	Default Louvre's cursor texture. More...

void	move (Float32 dx, Float32 dy)
	Move the cursor. More...

void	setPos (const LPointF &pos)
	Set the cursor position. More...

void	setPos (Float32 x, Float32 y)
	Set the cursor position. More...

const LPointF &	pos () const
	Get the current cursor position. More...

const LRect &	rect () const
	Get the cursor rect on the screen. More...

void	setHotspotB (const LPointF &hotspot)
	Set the cursor hotspot in buffer coordinates. More...

const LPointF &	hotspotB () const
	Get the current cursor hotspot in buffer coordinates. More...

void	setSize (const LSizeF &size)
	Set the cursor size. More...

void	setVisible (bool state)
	Change cursor visibility. More...

bool	visible () const
	Indicates whether the cursor is visible. More...

void	repaintOutputs (bool nonHardwareOnly=true)
	Repaint intersected outputs. More...

bool	hasHardwareSupport (const LOutput *output) const
	Check for hardware compositing support. More...

LOutput *	output () const
	Get the current cursor output. More...

const std::vector< LOutput * > &	intersectedOutputs () const
	Vector of intersected outputs. More...

Public Member Functions inherited from LObject
	LObject ()=default
	Constructor of the LObject class. More...

	~LObject ()
	Destructor of the LObject class. More...

std::shared_ptr< const bool >	isAlive () const
	Object's liveness status. More...

Additional Inherited Members
Static Public Member Functions inherited from LObject
static LCompositor *	compositor ()
	Quick access to the global compositor instance. More...

static LSeat *	seat ()
	Quick access to the global seat instance. More...

static LCursor *	cursor ()
	Quick access to the global cursor instance. More...

Member Function Documentation

◆ useDefault()

void useDefault ( )

Load the default cursor.

This method sets the cursor's texture and hotspot to the default values configured using replaceDefaultB().

The default texture initially matches defaultLouvreTexture() with a hotspot at (8, 8).

◆ replaceDefaultB()

void replaceDefaultB	(	const LTexture *	texture,
		const LPointF &	hotspot
	)

Replace Louvre's default cursor.

This method allows you to replace the Louvre's default cursor, which is set when useDefault() is called. You can specify a custom texture and hotspot for the new cursor. To restore Louvre's default cursor, pass nullptr as the texture.

Parameters

texture	The new texture to use as the default cursor, or `nullptr` to restore the default Louvre cursor.
hotspot	The hotspot position for the new cursor in buffer coordinates.

◆ setTextureB()

void setTextureB	(	const LTexture *	texture,
		const LPointF &	hotspot
	)

Set the cursor texture.

Assigns the texture and hotspot of the cursor. The texture size does not necessarily define the cursor size, setSize() must be used to assign the cursor size.

Parameters

texture	Texture to assign.
hotspot	Cursor hotspot in buffer coordinates.

◆ texture()

LTexture * texture ( ) const

Get the current cursor texture.

◆ defaultTexture()

LTexture * defaultTexture ( ) const

Get the default cursor texture.

This method returns the texture that has been set using replaceDefaultB(). Initially, the default texture is the same as defaultLouvreTexture().

Returns: A pointer to the default cursor texture.

◆ defaultHotspotB()

const LPointF & defaultHotspotB ( ) const

Get the default cursor hotspot.

This method returns the hotspot that has been set using replaceDefaultB(). Initially, the default hotspot is (8, 8).

Returns: A constant reference to the default cursor hotspot.

◆ defaultLouvreTexture()

LTexture * defaultLouvreTexture ( ) const

Default Louvre's cursor texture.

The default Louvre's cursor is the one shown in the image, with a size of 64x64 pixels and hotspot at (8,8).

◆ move()

void move	(	Float32	dx,
		Float32	dy
	)

Move the cursor.

Adjusts the cursor position by a delta (dx, dy) in surface coordinates.

Parameters

dx	Delta x in surface coordinates.
dy	Delta y in surface coordinates.

Note: Louvre automatically repositions the cursor if the new position is not within any output.

◆ setPos() [1/2]

void setPos ( const LPointF & pos )

Set the cursor position.

Sets the cursor position in surface coordinates.

Parameters

pos	The desired cursor position.

Note: Louvre automatically repositions the cursor if the specified position is not within any output.

◆ setPos() [2/2]

void setPos	(	Float32	x,
		Float32	y
	)

Set the cursor position.

Sets the cursor position in surface coordinates.

Parameters

x	The desired x cursor position.
y	The desired y cursor position.

Note: Louvre automatically repositions the cursor if the specified position is not within any output.

◆ pos()

const LPointF & pos ( ) const

Get the current cursor position.

Returns the current cursor position.

◆ rect()

const LRect & rect ( ) const

Get the cursor rect on the screen.

Returns the cursor rect, which is defined as LRect(pos - hotspot, size), in surface coordinates.

Use this rect and texture() to paint the cursor with LPainter when hardware composition is not supported.

◆ setHotspotB()

void setHotspotB ( const LPointF & hotspot )

Set the cursor hotspot in buffer coordinates.

The cursor hotspot is defined by coordinates relative to the origin of its buffer (upper left corner) and is used to position it correctly on the screen. For example, if the texture has a size of (64, 64), and the hotspot is at the center (32, 32), then the cursor's final screen position would be (x - 32, y - 32) for a cursor at position (x, y).

Note: The hotspot is automatically scaled proportionally to the cursor size.

Parameters

hotspot The desired hotspot in buffer coordinates.

◆ hotspotB()

const LPointF & hotspotB ( ) const

Get the current cursor hotspot in buffer coordinates.

◆ setSize()

void setSize ( const LSizeF & size )

Set the cursor size.

Sets the cursor size using surface coordinates. The texture and hotspot are automatically scaled, with the hotspot maintaining its proportion to the texture buffer size.

Note: You don't need to set the cursor size every time you change its texture or hotspot, Louvre automatically updates it.

The initial cursor size is (24, 24).

Parameters

size	The desired cursor size in surface coordinates.

◆ setVisible()

void setVisible ( bool state )

Change cursor visibility.

Shows or hides the cursor. If an output does not support hardware composition it is your responsibility to avoid rendering it when it is hidden.
You can use the visible() property to know if it is visible.

Parameters

state true makes the cursor visible and false hides it.

◆ visible()

bool visible ( ) const

Indicates whether the cursor is visible.

Returns: true if visible and false if hidden.

◆ repaintOutputs()

void repaintOutputs ( bool nonHardwareOnly = true )

Repaint intersected outputs.

Invokes LOutput::repaint() for each output in the list of intersected outputs.

Parameters

nonHardwareOnly If true, only repaints outputs that do not support hardware compositing.

◆ hasHardwareSupport()

bool hasHardwareSupport ( const LOutput * output ) const

Check for hardware compositing support.

Indicates whether the specified output supports hardware compositing.

Returns: true if hardware compositing is supported and false otherwise.

◆ output()

LOutput * output ( ) const

Get the current cursor output.

Returns a pointer to the output where the cursor is currently positioned.

Note: Louvre guarantees that the cursor is always within an output.

◆ intersectedOutputs()

const std::vector< LOutput * > & intersectedOutputs ( ) const

Vector of intersected outputs.

Returns a vector of initialized outputs that intersect with the cursor's rect() property.

Detailed Description

Hardware Composition

Smoother Hardware Cursor Updates

Public Member Functions

Additional Inherited Members

Member Function Documentation

◆ useDefault()

◆ replaceDefaultB()

◆ setTextureB()

◆ texture()

◆ defaultTexture()

◆ defaultHotspotB()

◆ defaultLouvreTexture()

◆ move()

◆ setPos() [1/2]

◆ setPos() [2/2]

◆ pos()

◆ rect()

◆ setHotspotB()

◆ hotspotB()

◆ setSize()

◆ setVisible()

◆ visible()

◆ repaintOutputs()

◆ hasHardwareSupport()

◆ output()

◆ intersectedOutputs()