![]() |
Louvre
v2.9.0-1
C++ library for Wayland compositors
|
A client "window". More...
Public Types | |
enum | Role : UInt32 |
ID of library roles. More... | |
enum | PointerConstraintMode |
Pointer constraint modes. More... | |
![]() | |
enum class | Type : Int32 |
Base factory object types. More... | |
Public Member Functions | |
LSurface (const void *params) noexcept | |
Constructor of the LSurface class. More... | |
~LSurface () | |
Destructor of the LSurface class. More... | |
LSurfaceLayer | layer () const noexcept |
Retrieves the layer in which this surface currently resides. More... | |
void | setPos (const LPoint &newPos) noexcept |
Assigns the position. More... | |
void | setPos (Int32 x, Int32 y) noexcept |
Assigns the position. More... | |
void | setX (Int32 x) noexcept |
Assigns the x component of the position. More... | |
void | setY (Int32 y) noexcept |
Assigns the y component of the position. More... | |
const LPoint & | pos () const noexcept |
Position given by the compositor. More... | |
const LPoint & | rolePos () const |
Role position. More... | |
const LSize & | sizeB () const noexcept |
Surface size in buffer coordinates. More... | |
const LSize & | size () const noexcept |
Surface size in surface coordinates. More... | |
const LRegion & | inputRegion () const noexcept |
Input region in surface coordinates. More... | |
const LRegion & | opaqueRegion () const noexcept |
Opaque region in surface coordinates. More... | |
const LRegion & | translucentRegion () const noexcept |
Translucent region in surface coordinates. More... | |
const LRegion & | damage () const noexcept |
Damaged region in surface coordinates. More... | |
const LRegion & | damageB () const noexcept |
Damaged region in buffer coordinates. More... | |
LContentType | contentType () const noexcept |
Returns the content type that the surface represents. More... | |
void | sendOutputEnterEvent (LOutput *output) noexcept |
Notify the client when the surface enters an output. More... | |
void | sendOutputLeaveEvent (LOutput *output) noexcept |
Notify the client when the surface leaves an output. More... | |
const std::vector< LOutput * > & | outputs () const noexcept |
Surface intersected outputs. More... | |
void | repaintOutputs () noexcept |
Repaints the intersected outputs. More... | |
bool | minimized () const noexcept |
Minimized property. More... | |
void | setMinimized (bool state) |
Sets the minimized property. More... | |
bool | receiveInput () const noexcept |
Input capability. More... | |
Int32 | bufferScale () const noexcept |
Buffer scale. More... | |
LTransform | bufferTransform () const noexcept |
Gets the buffer transform of the surface. More... | |
const LRectF & | srcRect () const noexcept |
Gets the source rect of the surface in surface coordinates. More... | |
bool | hasPointerFocus () const noexcept |
Check if the surface has pointer focus. More... | |
bool | hasKeyboardFocus () const noexcept |
Check if the surface has keyboard focus. More... | |
bool | hasKeyboardGrab () const noexcept |
Check if the surface is grabbing the keyboard. More... | |
LTexture * | texture () const noexcept |
OpenGL texture. More... | |
wl_buffer * | bufferResource () const noexcept |
Native wl_buffer handle. More... | |
bool | hasBuffer () const noexcept |
Indicates if the last attached buffer was NULL. More... | |
bool | hasDamage () const noexcept |
Presence of damage. More... | |
UInt32 | damageId () const noexcept |
Gets an ID that increments with each commit and new damage addition. More... | |
void | requestNextFrame (bool clearDamage=true) noexcept |
ACK the frame callback. More... | |
bool | mapped () const noexcept |
Mapped property. More... | |
bool | preferVSync () noexcept |
Gets the VSync preference of the client for this surface. More... | |
const std::vector< LSurfaceView * > & | views () const noexcept |
LSurfaceViews created for this surface. More... | |
Protocols::Wayland::RSurface * | surfaceResource () const noexcept |
Wayland surface resource. More... | |
LClient * | client () const noexcept |
Client owner of the surface. More... | |
LSurface * | parent () const noexcept |
Parent surface. More... | |
LSurface * | topmostParent () const noexcept |
Topmost parent of the surface. More... | |
const std::list< LSurface * > & | children () const noexcept |
Child surfaces. More... | |
bool | isPopupSubchild () const noexcept |
Check if the surface is a subchild of a popup. More... | |
bool | hasPopupSubchild () const noexcept |
Check if the surface has a subchild popup. More... | |
bool | isSubchildOf (LSurface *parent) const noexcept |
Check if the surface is a subchild of the specified parent surface. More... | |
void | raise () |
Raises the surface within its current layer. More... | |
LSurface * | prevSurface () const noexcept |
Retrieve the previous surface in the compositor surfaces list (LCompositor::surfaces()). More... | |
LSurface * | nextSurface () const noexcept |
Retrieve the next surface in the compositor surfaces list (LCompositor::surfaces()). More... | |
![]() | |
Type | factoryObjectType () const noexcept |
Gets the base factory object type. More... | |
![]() | |
LObject (const LObject &) noexcept | |
Copy constructor. More... | |
LObject & | operator= (const LObject &) noexcept |
Assignment operator (each object has its own individual LWeak reference count). More... | |
void | setUserData (UIntPtr data) const noexcept |
Store an unsigned integer value/pointer. More... | |
UIntPtr | userData () const noexcept |
Retrieves the stored unsigned integer value/pointer. More... | |
Roles | |
Role | roleId () const noexcept |
ID of the role. More... | |
LBaseSurfaceRole * | role () const noexcept |
Surface role. More... | |
LCursorRole * | cursorRole () const noexcept |
Cursor role. More... | |
LDNDIconRole * | dndIcon () const noexcept |
Drag & Drop icon role. More... | |
LToplevelRole * | toplevel () const noexcept |
Toplevel role. More... | |
LPopupRole * | popup () const noexcept |
Popup role. More... | |
LSubsurfaceRole * | subsurface () const noexcept |
Subsurface role. More... | |
LSessionLockRole * | sessionLock () const noexcept |
Session Lock role. More... | |
LLayerRole * | layerRole () const noexcept |
Layer role. More... | |
Pointer Constraints | |
Functionality related to pointer constraints.
| |
PointerConstraintMode | pointerConstraintMode () const noexcept |
Current pointer constraint mode. More... | |
virtual void | pointerConstraintModeChanged () |
Invoked when pointerConstraintMode() changes. More... | |
const LRegion & | pointerConstraintRegion () const noexcept |
Region within the surface where the pointer should be locked or confined if pointer constraint is enabled. More... | |
virtual void | pointerConstraintRegionChanged () |
Notifies a change in pointerConstraintRegion(). More... | |
void | enablePointerConstraint (bool enabled) |
Notifies the client if the pointer is constrained. More... | |
bool | pointerConstraintEnabled () const noexcept |
Indicates if the compositor enabled the pointer constraint for this surface. More... | |
const LPointF & | lockedPointerPosHint () const noexcept |
Indicates where the pointer currently is within the surface if the pointer Lock constrain mode is enabled. More... | |
virtual void | lockedPointerPosHintChanged () |
Notifies a change in lockedPointerPosHint(). More... | |
Virtual Methods | |
virtual void | damageChanged () |
Notifies about new damages on the surface. More... | |
virtual void | roleChanged () |
Notifies a change of role. More... | |
virtual void | parentChanged () |
Notifies a change of parent. More... | |
virtual void | mappingChanged () |
Notifies a change in the mapping state. More... | |
virtual void | bufferScaleChanged () |
Notifies a change in buffer scale. More... | |
virtual void | bufferTransformChanged () |
Notifies a change of the buffer transform. More... | |
virtual void | bufferSizeChanged () |
Notifies a change in buffer dimensions. More... | |
virtual void | sizeChanged () |
Notifies a change in the surface size. More... | |
virtual void | srcRectChanged () |
Notifies a change in the src rect. More... | |
virtual void | opaqueRegionChanged () |
Notifies of a change in the opaque region. More... | |
virtual void | inputRegionChanged () |
Notifies of a change in the input region. More... | |
virtual void | orderChanged () |
Notifies when the surface changes its position in the surfaces list. More... | |
virtual void | requestedRepaint () |
Request a repaint of the surface. More... | |
virtual void | minimizedChanged () |
Notifies about changes in the minimized state of the surface. More... | |
virtual void | preferVSyncChanged () |
Notifies about changes in the VSync preference. More... | |
virtual void | contentTypeChanged () |
Notifies a change of content type. More... | |
virtual void | layerChanged () |
Notified a c. More... | |
Additional Inherited Members | |
![]() | |
LObject () noexcept=default | |
Constructor of the LObject class. More... | |
virtual | ~LObject () noexcept |
Destructor of the LObject class. More... | |
void | notifyDestruction () noexcept |
Notifies the object destruction. More... | |
A client "window".
In the context of Wayland, surfaces can be thought of as analogous to "application windows." Each surface possesses attributes including position, size, buffer, input region, opaque region, damage region, and a designated role. Clients are responsible for rendering the content of their windows onto a buffer and subsequently transmitting it to the compositor, which is then displayed on the screen.
Surfaces on their own lack functionality. This is where roles come into play, as they establish the guidelines for how the compositor interacts with them, dictating their ordering, positioning, geometry interpretation, and more.
Louvre currently implements the following roles:
The surface's role can be accessed using the role() method or, if you already know the role in advance or wish to verify whether it matches one of them, through the dedicated functions: cursorRole(), dndIcon(), popup(), toplevel(), subsurface(), etc.
Typically, once a role is assigned, it remains consistent throughout the surface's entire lifecycle.
You have the option to monitor changes in the surface's role by utilizing the roleChanged() event.
To create additional roles beyond those offered by the library you can use the LBaseSurfaceRole class.
In order to render a surface, several conditions must be met, such as having an assigned role and a non-null buffer().
To determine if a surface is renderable, you can use the mapped() property. This property is false
when the client wants to hide it through some rule of its role, or when the necessary conditions for it to be rendered are not met.
To ensure that surfaces don't update their content more frequently than the refresh rate of the output (LOutput) they are displayed on, or in scenarios where they are obscured by other surfaces, callbacks are employed. Clients generate a callback resource and await the compositor's acknowledgment, signaling an optimal time to render the subsequent surface frame. To acknowledge the callback of a surface, use requestNextFrame().
The library automatically converts the surface's buffer into an object that can be used by the selected renderer.
Since the library currently only offers OpenGL ES 2.0 renderer, the buffer is converted to an OpenGL texture that can be accessed with texture().
It is also possible to access the native Wayland resource of the buffer with bufferResource().
To avoid the compositor redrawing the entire area of a surface on each frame, clients notify which regions have changed on their buffers, known as damage. You can access this region with damage() or damageB() and be notified when it changes with the damageChanged() event.
Louvre maintains a list to keep track of all surfaces created by clients, which can be accessed via LCompositor::surfaces().
This list adheres to the Z-axis order as defined by the protocols of their respective roles.
Surfaces are always assigned a layer, which is controlled by their role. Both the surfaces list and layers maintain the same order.
Surfaces are assigned to a layer as follows:
It is possible to modify the order of surfaces within a layer using the raise() method, this will normally also raise other surfaces such as subsurfaces.
You can receive notifications when the order changes by implementing the orderChanged() and layerChanged() virtual methods.
Use prevSurface() and nextSurface() to get the surface behind or on top of the current surface. Keep in mind that these functions may return nullptr
if a surface is at the beginning or end of the LCompositor::surfaces() list.
Surfaces are thought to be rendered in the order they appear in the list. The first surfaces should be located in the background, while the last ones should be in the foreground.
One of the characteristics of Wayland is that clients have very little information and control over how their surfaces are positioned on the screen.
For this reason, the rules of their roles generally define it based on an offset relative to another surface, an output or a position given by you.
Louvre simplifies this by allowing you to assign the position of the surfaces with setPos() and access the position suggested by its role with rolePos().
In some cases, such as in the LPopupRole or LSubsurfaceRole role, the position set with setPos() is not taken into account.
You can see the positioning rules of each role in detail by viewing the documentation of rolePos() for each one.
ID of library roles.
ID of the current role of the surface accessible with roleId()
Enumerator | |
---|---|
Undefined | No role set. |
Toplevel | |
Popup | |
Subsurface | |
Cursor | |
DNDIcon | |
SessionLock | LSessionLockRole (since v2.0.0) |
Layer | LLayerRole (since v2.0.0) |
Pointer constraint modes.
Enumerator | |
---|---|
Free | No pointer constraint, the pointer is free to move anywhere. |
Lock | Lock the pointer position somewhere inside pointerConstraintRegion(). |
Confine | Confine the pointer to pointerConstraintRegion(). |
|
noexcept |
Constructor of the LSurface class.
params | Internal parameters provided in LCompositor::createObjectRequest(). |
~LSurface | ( | ) |
Destructor of the LSurface class.
Invoked after LCompositor::onAnticipatedObjectDestruction().
|
noexcept |
Retrieves the layer in which this surface currently resides.
|
noexcept |
Assigns the position.
Assigns the position of the surface.
Assigns the position.
Assigns the position of the surface.
|
noexcept |
Assigns the x component of the position.
Assigns the x component of the position of the surface.
|
noexcept |
Assigns the y component of the position.
Assigns the y component of the position of the surface.
|
noexcept |
const LPoint & rolePos | ( | ) | const |
Role position.
Role position in surface coordinates. If the surface has no role, the same value as pos() is returned.
|
noexcept |
Surface size in buffer coordinates.
|
noexcept |
Surface size in surface coordinates.
|
noexcept |
Input region in surface coordinates.
Region of the surface that is capable of receiving input, in surface coordinates.
|
noexcept |
Opaque region in surface coordinates.
|
noexcept |
Translucent region in surface coordinates.
Translucent region in surface coordinates (inverted opaque region).
|
noexcept |
Damaged region in surface coordinates.
|
noexcept |
Damaged region in buffer coordinates.
|
noexcept |
Returns the content type that the surface represents.
Clients using the Content Type Hint protocol can indicate the type of content a particular surface is displaying.
This information can be used, for example, to adapt the compositor behavior and to optimize the functioning of hardware displays when assigned to outputs through LOutput::setContentType().
The default value is LContentTypeNone.
|
noexcept |
Notify the client when the surface enters an output.
This method notifies the surface's client that the surface has become visible within the display area of a specific output. The client application can use this information to synchronize the surface's scale with that of the output. You can access the list of outputs where the surface is visible using the outputs() method.
output | The output into which the surface has entered. |
|
noexcept |
Notify the client when the surface leaves an output.
This method informs the surface's client application that the surface is no longer visible on a particular output. You can access the list of outputs where the surface is still visible using the outputs() method.
output | The output from which the surface is no longer visible. |
|
noexcept |
Surface intersected outputs.
Vector of output pointers in which the surface is visible, modifiable with the sendOutputEnterEvent() and sendOutputLeaveEvent() methods.
|
noexcept |
Repaints the intersected outputs.
Invokes the LOutput::repaint() method on all outputs listed in outputs().
|
noexcept |
Minimized property.
Stores the minimized state of the surface set with setMinimized().
true
if the surface is minimized and false
otherwise. void setMinimized | ( | bool | state | ) |
Sets the minimized property.
Minimize/unminimize the surface and all its children.
|
noexcept |
Input capability.
Indicates whether the surface is able to receive pointer or touch input events.
|
noexcept |
Buffer scale.
Scale of the surface buffer. You can listen for changes to this property with the bufferScaleChanged() event.
|
noexcept |
Gets the buffer transform of the surface.
|
noexcept |
Gets the source rect of the surface in surface coordinates.
For clients using the Viewporter protocol, a custom srcRect() detached from the buffer size can be specified. For clients not using the protocol, the source rect covers the entire surface buffer.
|
noexcept |
Check if the surface has pointer focus.
true
if the surface has pointer focus, false
otherwise.
|
noexcept |
Check if the surface has keyboard focus.
true
if the surface has keyboard focus, false
otherwise.
|
noexcept |
Check if the surface is grabbing the keyboard.
true
if the surface is grabbing the keyboard, false
otherwise.
|
noexcept |
OpenGL texture.
Representation of the surface's buffer as an OpenGL texture.
nullptr
if the surface is not currently mapped.
|
noexcept |
Native wl_buffer handle.
Handle to the last commited Wayland buffer of the surface.
nullptr
if the surface is not currently mapped.
|
noexcept |
Indicates if the last attached buffer was NULL.
true
, bufferResource() may return nullptr
if the buffer was destroyed before being replaced by another attach and commit.true
if the last attached buffer was not NULL, otherwise false
.
|
noexcept |
Presence of damage.
Indicates if the surface has new damage since the last time the requestNextFrame() method was called.
You can access the damaged region with damage() or damageB().
|
noexcept |
Gets an ID that increments with each commit and new damage addition.
The ID increments every time the surface is committed and new damage is added.
|
noexcept |
ACK the frame callback.
Notifies the surface that it's time for it to draw its next frame.
If not called, the given surface should not update its content.
|
noexcept |
Mapped property.
Indicates if the surface can be rendered.
|
noexcept |
Gets the VSync preference of the client for this surface.
true
if VSync is preferred, false
if tearing is preferred.
|
noexcept |
LSurfaceViews created for this surface.
|
noexcept |
Wayland surface resource.
Returns the resource generated by the wl_surface interface of the Wayland protocol.
|
noexcept |
Client owner of the surface.
|
noexcept |
Parent surface.
nullptr
if it does not have a parent.
|
noexcept |
Topmost parent of the surface.
nullptr
if it does not have a parent.
|
noexcept |
Child surfaces.
List of child surfaces.
|
noexcept |
Check if the surface is a subchild of a popup.
This method determines whether the surface is a subchild of a popup surface. It returns true
if the surface is a subchild of a popup surface in the hierarchy; otherwise, it returns false
.
true
if the surface is a subchild of a popup surface, false
otherwise.
|
noexcept |
Check if the surface has a subchild popup.
This method checks whether the surface has a subchild popup surface. It returns true
if the surface has a popup subchild; otherwise, it returns false
.
true
if the surface has a subchild popup, false
otherwise.
|
noexcept |
Check if the surface is a subchild of the specified parent surface.
This method checks whether the surface is a subchild of the provided parent surface.
parent | A pointer to the potential parent LSurface to check against. |
true
if the surface is a subchild of the provided parent surface, false
otherwise. void raise | ( | ) |
Raises the surface within its current layer.
This method reinserts the surface at the end of its current layer's list, ensuring its position above other surfaces within the same layer.
If the surface is parent of other surfaces, those child surfaces will also be raised to maintain the hierarchical order required by certain protocols.
orderChanged()
event is not allowed, and doing so will result in a no-op.
|
noexcept |
Retrieve the previous surface in the compositor surfaces list (LCompositor::surfaces()).
This method returns a pointer to the surface that precedes the current surface in the compositor's surfaces list. If the current surface is the first one in the list, the method returns nullptr
.
nullptr
if the current surface is the first in the list.
|
noexcept |
Retrieve the next surface in the compositor surfaces list (LCompositor::surfaces()).
This method returns a pointer to the surface that follows the current surface in the compositor's surfaces list. If the current surface is the last one in the list, the method returns nullptr
.
nullptr
if the current surface is the last in the list.
|
noexcept |
ID of the role.
|
noexcept |
Surface role.
nullptr
if it does not have a role.
|
noexcept |
Cursor role.
nullptr
if it has a different role.
|
noexcept |
Drag & Drop icon role.
nullptr
if it has a different role.
|
noexcept |
Toplevel role.
nullptr
if it has a different role.
|
noexcept |
Popup role.
nullptr
if it has a different role.
|
noexcept |
Subsurface role.
nullptr
if it has a different role.
|
noexcept |
Session Lock role.
nullptr
if it has a different role.
|
noexcept |
Layer role.
nullptr
if it has a different role.
|
noexcept |
Current pointer constraint mode.
Returns the current mode in which the client wants to constrain the pointer.
|
virtual |
Invoked when pointerConstraintMode() changes.
Each time the pointer constraint mode changes, the pointer constraint is disabled and enablePointerConstraint() must be called again to enable it.
|
noexcept |
Region within the surface where the pointer should be locked or confined if pointer constraint is enabled.
Returns the region within the surface where the pointer should be locked or confined if the pointer constraint is enabled.
|
virtual |
Notifies a change in pointerConstraintRegion().
void enablePointerConstraint | ( | bool | enabled | ) |
Notifies the client if the pointer is constrained.
The surface must have pointer focus prior to calling this method and have either a Lock or Confine PointerConstraintMode, otherwise, it is a no-op.
enabled | Boolean indicating if the pointer constraint is enabled. |
|
noexcept |
Indicates if the compositor enabled the pointer constraint for this surface.
It is automatically set to false
if the surface loses pointer focus or the pointerConstraintMode() property changes.
true
if the pointer constraint is enabled for this surface, false
otherwise.
|
noexcept |
Indicates where the pointer currently is within the surface if the pointer Lock constrain mode is enabled.
If pointerConstraintMode() is not Lock or the client has never set this property, it returns (-1.f, -1.f)
.
|
virtual |
Notifies a change in lockedPointerPosHint().
|
virtual |
Notifies about new damages on the surface.
Reimplement this virtual method if you want to be notified when the surface has new damage.
|
virtual |
Notifies a change of role.
Reimplement this virtual method if you want to be notified when the surface changes its role.
|
virtual |
Notifies a change of parent.
Reimplement this virtual method if you want to be notified when the surface changes its parent.
|
virtual |
Notifies a change in the mapping state.
Reimplement this virtual method if you want to be notified when the surface changes its mapping state.
|
virtual |
Notifies a change in buffer scale.
Reimplement this virtual method if you want to be notified when the surface's buffer scale changes.
|
virtual |
|
virtual |
Notifies a change in buffer dimensions.
Reimplement this virtual method if you want to be notified when the buffer size (sizeB()) changes.
|
virtual |
Notifies a change in the surface size.
Reimplement this virtual method if you want to be notified when the surface size() changes.
|
virtual |
Notifies a change in the src rect.
Reimplement this virtual method if you want to be notified when srcRect() changes.
|
virtual |
|
virtual |
Notifies of a change in the input region.
Reimplement this virtual method if you want to be notified when the surface changes its input region.
|
virtual |
Notifies when the surface changes its position in the surfaces list.
Override this virtual method if you wish to be informed about changes in the order of the surface within the compositor's list of surfaces.
|
virtual |
Request a repaint of the surface.
This request can be initiated either by the library or by the client, serving as an explicit command to repaint the surface.
|
virtual |
Notifies about changes in the minimized state of the surface.
This method is called to signal changes in the minimized state of the surface.
|
virtual |
Notifies about changes in the VSync preference.
This event is triggered when the preferVSync() property changes.
|
virtual |
Notifies a change of content type.
This event is triggered when the contentType() property changes.
|
virtual |
Notified a c.
This event is triggered when the layer() property changes.