LCompositor Class Reference

Louvre's core and objects factory. More...

Public Types
enum	CompositorState
	Compositor state. More...

Public Member Functions
	LCompositor () noexcept
	Constructor of the LCompositor class. More...
virtual	~LCompositor ()
	Destructor of the LCompositor class. More...
CompositorState	state () const noexcept
	Gets the current compositor state. More...
bool	start ()
	Starts the main event loop and backends. More...
Int32	processLoop (Int32 msTimeout)
	Process the compositor's main event loop. More...
Int32	fd () const noexcept
	Gets a pollable file descriptor of the main event loop. More...
void	finish () noexcept
	Uninitializes the compositor. More...
LCursor *	cursor () const noexcept
	Gets the compositor cursor. More...
LSeat *	seat () const noexcept
	Gets the compositor seat. More...
LSessionLockManager *	sessionLockManager () const noexcept
	Provides access to the session lock manager. More...
const std::list< LSurface * > &	surfaces () const noexcept
	Gets a list of all surfaces created by clients. More...
const std::list< LSurface * > &	layer (LSurfaceLayer layer) const noexcept
	Retrieves the list of surfaces within a specific layer. More...
const std::vector< LClient * > &	clients () const noexcept
	Gets a list of clients connected to the compositor. More...
LClient *	getClientFromNativeResource (const wl_client *client) noexcept
	Gets the LClient of a native Wayland wl_client resource. More...
const std::vector< LOutput * > &	outputs () const noexcept
	Gets a vector of all initialized outputs. More...
bool	addOutput (LOutput *output)
	Initializes the specified output. More...
void	removeOutput (LOutput *output)
	Uninitializes the specified output. More...
void	repaintAllOutputs () noexcept
	Unlocks the rendering thread of all initialized outputs. More...
LOutput *	mostIntersectedOutput (const LRect &rect, bool initializedOnly=true) const noexcept
	Searches for the most intersected output. More...
std::thread::id	mainThreadId () const noexcept
	Identifier of the main thread. More...
const std::filesystem::path &	defaultAssetsPath () const noexcept
	Gets the absolute path to the default Louvre assets directory. More...
const std::filesystem::path &	defaultBackendsPath () const noexcept
	Gets the absolute path to the default Louvre backends directory. More...
bool	loadGraphicBackend (const std::filesystem::path &path) noexcept
	Loads a graphic backend (dynamic library). More...
bool	isGraphicBackendInitialized () const noexcept
	Checks if the graphic backend is initialized. More...
const std::string &	defaultGraphicBackendName () const noexcept
	Gets the name of the default graphic backend. More...
void *	graphicBackendContextHandle () const noexcept
	Handle to the native context used by the graphic backend. More...
UInt32	graphicBackendId () const noexcept
	Gets the ID of the current graphic backend. More...
bool	loadInputBackend (const std::filesystem::path &path) noexcept
	Loads an input backend (dynamic library). More...
bool	isInputBackendInitialized () const noexcept
	Checks if the input backend is initialized. More...
const std::string &	defaultInputBackendName () const noexcept
	Gets the name of the default input backend. More...
void *	inputBackendContextHandle () const noexcept
	Handle to the native context used by the input backend. More...
UInt32	inputBackendId () const noexcept
	Gets the ID of the current input backend. More...
template<class Global >
LGlobal *	createGlobal (void *data=nullptr) noexcept
	Creates and adds a global to the compositor. More...
void	removeGlobal (LGlobal *global) noexcept
	Safely removes a global. More...

Static Public Member Functions
static const LVersion &	version () noexcept
	Gets the current Louvre version. More...
static wl_display *	display () noexcept
	Gets the native wl_display used by the compositor. More...
static wl_event_source *	addFdListener (int fd, void *userData, int(*callback)(int, unsigned int, void *), UInt32 flags=WL_EVENT_READABLE)
	Adds a pollable file descriptor listener to the main event loop. More...
static void	removeFdListener (wl_event_source *source)
	Removes a previously added file descriptor from the compositor's event loop. More...
static void	flushClients () noexcept
	Flush all pending client events. More...
static EGLDisplay	eglDisplay () noexcept
	Gets the main EGL display created by the graphic backend. More...
static EGLContext	eglContext () noexcept
	Gets the main EGL context created by the graphic backend. More...

Virtual Methods
virtual void	initialized ()
	Notifies a successful compositor initialization. More...
virtual void	uninitialized ()
	Notifies the uninitialization of the compositor. More...
virtual LFactoryObject *	createObjectRequest (LFactoryObject::Type objectType, const void *params)
	Request to create a specific LFactoryObject. More...
virtual void	onAnticipatedObjectDestruction (LFactoryObject *object)
	Announce the anticipated destruction of an LFactoryObject. More...
virtual bool	createGlobalsRequest ()
	Wayland globals initialization. More...
virtual bool	globalsFilter (LClient *client, LGlobal *global)
	Globals filter. More...

Detailed Description

Louvre's core and objects factory.

The LCompositor class manages the main event loop, backend systems, and provides virtual constructors and destructors for Louvre objects with interfaces you can override.

See also

LFactoryObject

createObjectRequest()

onAnticipatedObjectDestruction()

Member Enumeration Documentation

CompositorState

enum CompositorState

Compositor state.

See also

state().

Enumerator
Uninitialized	Uninitialized.
Initializing	Changing from uninitialized to initialized.
Initialized	Initialized.
Uninitializing	Changing from any state to uninitialized.
Pausing	Changing from initialized to paused.
Paused	Idle state during a session (TTY) switch.
Resuming	Changing from paused to initialized.

Constructor & Destructor Documentation

LCompositor()

LCompositor ( )

noexcept

Constructor of the LCompositor class.

~LCompositor()

~LCompositor ( )

virtualdefault

Destructor of the LCompositor class.

Member Function Documentation

version()

const LVersion & version ( )

staticnoexcept

Gets the current Louvre version.

state()

LCompositor::CompositorState state ( ) const

noexcept

Gets the current compositor state.

start()

bool start

(

)

Starts the main event loop and backends.

After successful initialization, notified with the initialized() event, the compositor can receive connections from Wayland clients and initialize output rendering threads using the addOutput() method.

Returns

false on failure and true otherwise.

processLoop()

Int32 processLoop

(

Int32

msTimeout

)

Process the compositor's main event loop.

Note

You can also get a pollable file descriptor with fd().

Parameters

msTimeout

Milliseconds to wait before an event occurs. Setting it to 0 disables the timeout, and setting it to -1 makes it wait indefinitely until an event occurs.

Returns

1 on success and 0 on failure.

fd()

Int32 fd ( ) const

noexcept

Gets a pollable file descriptor of the main event loop.

finish()

void finish ( )

noexcept

Uninitializes the compositor.

See also

uninitialized().

display()

wl_display * display ( )

staticnoexcept

Gets the native wl_display used by the compositor.

Returns

The native wl_display.

addFdListener()

wl_event_source * addFdListener ( int  fd, void *  userData, int(*)(int, unsigned int, void *)  callback, UInt32  flags = WL_EVENT_READABLE  )

static

Adds a pollable file descriptor listener to the main event loop.

Parameters

fd	The file descriptor to be added.
userData	User data to pass to the callback function.
callback	The callback function to handle events on the file descriptor.
flags	Flags to specify the type of event to listen for (e.g., WL_EVENT_READABLE).

Note

If the compositor is suspended, events are queued and will be dispatched once it is resumed.

Returns

The wl_event_source associated with the added file descriptor.

removeFdListener()

void removeFdListener ( wl_event_source *  source )

static

Removes a previously added file descriptor from the compositor's event loop.

Parameters

source

The wl_event_source to remove.

cursor()

LCursor * cursor ( ) const

noexcept

Gets the compositor cursor.

This method must be accessed within or after the initialized() or cursorInitialized() events. If the cursor has not yet been initialized, this method returns nullptr.

Returns

A pointer to the LCursor instance or nullptr if not yet initialized.

seat()

LSeat * seat ( ) const

noexcept

Gets the compositor seat.

The seat provides access to the LPointer, LKeyboard, LTouch, and LOutput instances.

Returns

A pointer to the LSeat instance.

sessionLockManager()

LSessionLockManager * sessionLockManager ( ) const

noexcept

Provides access to the session lock manager.

The session lock manager allows you to handle client requests to lock the user session and display arbitrary content.

Returns

A pointer to the LSessionLockManager instance.

surfaces()

const std::list< LSurface * > & surfaces ( ) const

noexcept

Gets a list of all surfaces created by clients.

This method returns a list of all surfaces created by clients, respecting the stacking order of their roles protocols.
To access surfaces from a specific layer, used layer() instead.

Returns

A list of LSurface objects representing the surfaces.

layer()

const std::list< LSurface * > & layer ( LSurfaceLayer  layer ) const

noexcept

Retrieves the list of surfaces within a specific layer.

Note

The layers lists follow the same order as surfaces().

Parameters

layer

The layer index to retrieve. See LSurfaceLayer.

Returns

A reference to a list of pointers to LSurface objects within the specified layer.

clients()

const std::vector< LClient * > & clients ( ) const

noexcept

Gets a list of clients connected to the compositor.

This method returns a list of clients that are currently connected to the compositor.

Returns

A list of LClient objects representing the connected clients.

flushClients()

void flushClients ( )

staticnoexcept

Flush all pending client events.

This method immediatly flushes all pending client events.

getClientFromNativeResource()

LClient * getClientFromNativeResource ( const wl_client *  client )

noexcept

Gets the LClient of a native Wayland wl_client resource.

Returns

The LClient instance for a wl_client resource or nullptr if not found.

outputs()

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

noexcept

Gets a vector of all initialized outputs.

This method returns a vector of all outputs that have been initialized using the addOutput() method.

Note

This vector only contains initialized outputs. To get all available outputs, use LSeat::outputs() instead.

addOutput()

bool addOutput

(

LOutput *

output

)

Initializes the specified output.

This method creates a new rendering thread and initializes the specified output. Once initialized, the LOutput::initializeGL() event is triggered, and LOutput::repaint() can be used to unlock the rendering thread loop, which triggers LOutput::paintGL() events.

This adds the output to the outputs() vector.

Note

Adding an already initialized output is a no-op.

Parameters

output

The output to initialize, obtained from LSeat::outputs().

Returns

true on success, false on failure.

removeOutput()

void removeOutput

(

LOutput *

output

)

Uninitializes the specified output.

This method uninitializes and removes the specified output from the compositor, stopping its thread, rendering loop and triggering the LOutput::uninitializeGL() event.

Note

Removing an output that has not been added to the compositor is a no-op.

Warning

Calling this method from the same rendering thread of the output (whithin any of its ...GL() events) has no effect. Doing so would lead to a deadlock, so Louvre simply ignores the request.

Parameters

output

The output to remove, previously added to the compositor. See outputs().

repaintAllOutputs()

void repaintAllOutputs ( )

noexcept

Unlocks the rendering thread of all initialized outputs.

This method schedules a new rendering frame by calling the LOutput::repaint() method to all initialized outputs.

mostIntersectedOutput()

LOutput * mostIntersectedOutput ( const LRect &  rect, bool  initializedOnly = true  ) const

noexcept

Searches for the most intersected output.

Checks which output within the global compositor space intersects the given rectangle the most.

Parameters

rect	The rectangle to check in compositor-global coordinates.
initializedOnly	If true, only considers initialized outputs. Default is true.

Returns

A pointer to the most intersected LOutput, or nullptr if no output is found.

mainThreadId()

std::thread::id mainThreadId ( ) const

noexcept

Identifier of the main thread.

This ID corresponds to the primary thread responsible for managing the Wayland and input backend event loops, while individual output operations are performed on separate threads.

Returns

The identifier of the main thread.

eglDisplay()

EGLDisplay eglDisplay ( )

staticnoexcept

Gets the main EGL display created by the graphic backend.

eglContext()

EGLContext eglContext ( )

staticnoexcept

Gets the main EGL context created by the graphic backend.

defaultAssetsPath()

const std::filesystem::path & defaultAssetsPath ( ) const

noexcept

Gets the absolute path to the default Louvre assets directory.

This path is automatically generated by Meson and should point to PREFIX/DATADIR/Louvre/assets.

Returns

The absolute path to the default Louvre assets directory.

defaultBackendsPath()

const std::filesystem::path & defaultBackendsPath ( ) const

noexcept

Gets the absolute path to the default Louvre backends directory.

This path is automatically generated by Meson and should point to PREFIX/LIBDIR/Louvre/backends.
Used when the LOUVRE_BACKENDS_PATH environment variable is unset.

Returns

The absolute path to the default Louvre backends directory.

loadGraphicBackend()

bool loadGraphicBackend ( const std::filesystem::path &  path )

noexcept

Loads a graphic backend (dynamic library).

Use this method to load a custom graphic backend before calling start().
By default, Louvre tries to load the Wayland backend if WAYLAND_DISPLAY is set, and then the DRM backend if fails.

Note

Instead of using this method, a more preferable approach is to let the user choose the graphical backend by configuring the LOUVRE_BACKENDS_PATH and LOUVRE_GRAPHIC_BACKEND environment variables.

Parameters

path	Absolute path of the dynamic library.

Returns

true if the backend is successfully loaded, false otherwise.

isGraphicBackendInitialized()

bool isGraphicBackendInitialized ( ) const

noexcept

Checks if the graphic backend is initialized.

Use this method to determine whether the graphic backend has been initialized after calling start().

Returns

true if the graphic backend is initialized, false otherwise.

defaultGraphicBackendName()

const std::string & defaultGraphicBackendName ( ) const

noexcept

Gets the name of the default graphic backend.

This name is used when the LOUVRE_GRAPHIC_BACKEND environment variable is unset.
It is automatically generated by Meson and defaults to drm.

Returns

The name of the default graphic backend.

graphicBackendContextHandle()

void * graphicBackendContextHandle ( ) const

noexcept

Handle to the native context used by the graphic backend.

This opaque handle is unique to each graphic backend.

• In the case of the DRM backend, it returns a pointer to a SRMCore struct.
• In the case of the Wayland backend, it returns a pointer to a wl_display struct.

You can use this handle to configure specific aspects of each backend.

graphicBackendId()

UInt32 graphicBackendId ( ) const

noexcept

Gets the ID of the current graphic backend.

Each graphic backend is assigned a unique UInt32 ID. You can use this method to retrieve the ID of the current graphic backend in use.

The IDs of graphic backends shipped with Louvre are listed in the LGraphicBackendID enum.

Returns

The ID of the graphic backend.

loadInputBackend()

bool loadInputBackend ( const std::filesystem::path &  path )

noexcept

Loads an input backend (dynamic library).

Use this method to load a custom graphic backend before calling start().
By default, Louvre tries to load the Wayland backend if WAYLAND_DISPLAY is set, and then the Libinput backend if fails.

Note

Instead of using this method, a more preferable approach is to let the user choose the graphical backend by configuring the LOUVRE_BACKENDS_PATH and LOUVRE_INPUT_BACKEND environment variables.

Parameters

path	Location of the backend's dynamic library.

Returns

true if the backend is successfully loaded, false otherwise.

isInputBackendInitialized()

bool isInputBackendInitialized ( ) const

noexcept

Checks if the input backend is initialized.

Use this method to determine whether the input backend has been initialized after calling start().

Returns

true if the input backend is initialized, false otherwise.

defaultInputBackendName()

const std::string & defaultInputBackendName ( ) const

noexcept

Gets the name of the default input backend.

This name is used when the LOUVRE_INPUT_BACKEND environment variable is unset.
It is automatically generated by Meson and defaults to libinput.

Returns

The name of the default input backend.

inputBackendContextHandle()

void * inputBackendContextHandle ( ) const

noexcept

Handle to the native context used by the input backend.

This opaque handle is unique to each input backend.

• In the case of the Libinput backend, it returns a pointer to a libinput struct.
• In the case of the Wayland backend, it returns a pointer to a wl_display struct.

You can use this handle to configure specific aspects of each backend.

inputBackendId()

UInt32 inputBackendId ( ) const

noexcept

Gets the ID of the current input backend.

Each input backend is assigned a unique Louvre::UInt32 ID. You can use this method to retrieve the ID of the current input backend in use.

The IDs of input backends shipped with Louvre are listed in the Louvre::LInputBackendID enum.

Returns

The ID of the input backend.

createGlobal()

LGlobal* createGlobal ( void *  data = nullptr )

inlinenoexcept

Creates and adds a global to the compositor.

This method creates and adds a global to the compositor. Globals implemented by Louvre can be found in <protocols/{protocol}/G{global}.h>.

Louvre automatically creates all the supported globals during compositor initialization. See LCompositor::createGlobalsRequest().

Template Parameters

Global

The type of global to create. It should be a subclass of Louvre::LResource.

Returns

Pointer to the created LGlobal instance, which can be later removed with removeGlobal().

removeGlobal()

void removeGlobal ( LGlobal *  global )

noexcept

Safely removes a global.

This method performs a lazy removal of an LGlobal created with createGlobal(), ensuring clients are notified before it is destroyed.

Note

Calling LCompositor::removeGlobal() isn't mandatory as globals are automatically destroyed during the compositor's uninitialization.

Warning

After calling this method, the LGlobal instance must no longer be used as it is going to be destroyed.

Parameters

global

Pointer to the LGlobal instance to remove.

initialized()

virtual void initialized ( )

virtual

Notifies a successful compositor initialization.

Use this event to handle the successful initialization of the compositor after calling start().
Here you should perform initial configuration tasks, such as setting up outputs, as demonstrated in the default implementation.

Warning

Avoid interacting with any LFactoryObjects (e.g., LPointer, LKeyboard, LTouch, etc.) or creating LTextures before this event. These objects or the input/graphic backends might be partially initialized, and interacting with them could cause a segmentation fault.

Default Implementation

void LCompositor::initialized()
{
    Int32 totalWidth = 0;
 
    // Initializes and arranges outputs from left to right
    for (LOutput *output : seat()->outputs())
    {
        // Sets a scale factor of 2 when DPI >= 200
        output->setScale(output->dpi() >= 200 ? 2.f : 1.f);
 
        // Change it if any of your displays is rotated/flipped
        output->setTransform(LTransform::Normal);
 
        output->setPos(LPoint(totalWidth, 0));
        totalWidth += output->size().w();
        addOutput(output);
        output->repaint();
    }
}

uninitialized()

virtual void uninitialized ( )

virtual

Notifies the uninitialization of the compositor.

This event is triggered right before the compositor is uninitialized when finish() is called. At this point, both the input and graphic backends, along with other resources such as connected clients and initialized outputs, are still operational.
Use this opportunity to release any compositor-specific resources that you may have created.

Default Implementation

void LCompositor::uninitialized()
{
    /* No default implementation */
}

createObjectRequest()

virtual LFactoryObject* createObjectRequest ( LFactoryObject::Type  objectType, const void *  params  )

virtual

Request to create a specific LFactoryObject.

Certain classes in Louvre have an interface that can be overridden.
Instances of these classes can only be created from this virtual constructor when requested by the compositor.
Refer to LFactoryObject::Type to see all the classes that can be overridden.

Parameters

objectType	Indicates the type of the class instance to return.
params	An opaque data type that should be passed to the object's constructor.

Returns

If nullptr is returned, Louvre will create an instance of the object using the base class.

Default Implementation

LFactoryObject *LCompositor::createObjectRequest(LFactoryObject::Type objectType, const void *params)
{
    L_UNUSED(objectType)
    L_UNUSED(params)
 
    /* If nullptr is returned, Louvre creates an instance of the base class */
    return nullptr;
}

onAnticipatedObjectDestruction()

virtual void onAnticipatedObjectDestruction ( LFactoryObject *  object )

virtual

Announce the anticipated destruction of an LFactoryObject.

When an LFactoryObject destructor is invoked, it is likely that associated resources are no longer available.
Using this event, however, provides an opportunity to access those resources.

Warning

Do not delete the object, Louvre deletes it later.

Parameters

object

The object for which destruction is anticipated.

Default Implementation

void LCompositor::onAnticipatedObjectDestruction(LFactoryObject *object)
{
    L_UNUSED(object)
}

createGlobalsRequest()

virtual bool createGlobalsRequest ( )

virtual

Wayland globals initialization.

Override this method if you want to remove or add custom Wayland globals.

See also

createGlobal()

removeGlobal()

Returns

true on success, false on failure (prevents the compositor from starting).

Default Implementation

bool LCompositor::createGlobalsRequest()
{
    // Allow clients to create surfaces and regions
    createGlobal<Wayland::GCompositor>();
 
    // Allow clients to receive pointer, keyboard, and touch events
    createGlobal<Wayland::GSeat>();
 
    // Provides detailed information of pointer movement
    createGlobal<RelativePointer::GRelativePointerManager>();
 
    // Allow clients to request setting pointer constraints
    createGlobal<PointerConstraints::GPointerConstraints>();
 
    // Allow clients to receive swipe, pinch, and hold pointer gestures
    createGlobal<PointerGestures::GPointerGestures>();
 
    // Enable drag & drop and clipboard data sharing between clients
    createGlobal<Wayland::GDataDeviceManager>();
 
    // Allow clients to create subsurface roles
    createGlobal<Wayland::GSubcompositor>();
 
    // Allow clients to create toplevel and popup roles
    createGlobal<XdgShell::GXdgWmBase>();
 
    // Allow clients to request modifying the state of foreign toplevels
    createGlobal<ForeignToplevelManagement::GForeignToplevelManager>();
 
    // Provides additional info about outputs
    createGlobal<XdgOutput::GXdgOutputManager>();
 
    // Allow negotiation of server-side or client-side decorations
    createGlobal<XdgDecoration::GXdgDecorationManager>();
 
    // Allow clients to adjust their surfaces buffers to fractional scales
    createGlobal<FractionalScale::GFractionalScaleManager>();
 
    // Allow clients to request setting the gamma LUT of outputs
    createGlobal<GammaControl::GGammaControlManager>();
 
    // Allow clients to create DMA buffers
    if (!LTexture::supportedDMAFormats().empty())
        createGlobal<LinuxDMABuf::GLinuxDMABuf>();
 
    // Provides detailed information of how the surfaces are presented
    createGlobal<PresentationTime::GPresentation>();
 
    // Allows clients to request locking the user session with arbitrary graphics
    createGlobal<SessionLock::GSessionLockManager>();
 
    // Allows clients to notify their preference of vsync for specific surfaces
    createGlobal<TearingControl::GTearingControlManager>();
 
    // Allow clients to clip and scale buffers
    createGlobal<Viewporter::GViewporter>();
 
    // Allow clients to capture outputs
    createGlobal<ScreenCopy::GScreenCopyManager>();
 
    // Allow clients to create wlr_layer_shell surfaces
    createGlobal<LayerShell::GLayerShell>();
 
    // Allow clients to create single pixel buffers (requires Viewporter::GViewporter)
    createGlobal<SinglePixelBuffer::GSinglePixelBufferManager>();
 
    // Allows clients to provide a hint about the content type being displayed by surfaces
    createGlobal<ContentType::GContentTypeManager>();
 
    return true;
}

globalsFilter()

virtual bool globalsFilter ( LClient *  client, LGlobal *  global  )

virtual

Globals filter.

Filter to prevent clients from using specific protocol globals.
It is recommended to use this method to allow only well-known clients to bind to protocols such as Session Lock, Wlr Screen Copy, and others.

See LClient::credentials() and LGlobal::isType().

Parameters

client	The client attempting to bind to the global.
global	The protocol global the client is attempting to bind to.

Returns

true to allow the client, false to deny it.

Default Implementation

The default implementation allows all clients to bind to all globals.

bool LCompositor::globalsFilter(LClient *client, LGlobal *global)
{
    L_UNUSED(client)
    L_UNUSED(global)
    return true;
}