Background blur controller for surfaces. More...

#include <LBackgroundBlur.h>

Inheritance diagram for LBackgroundBlur:

Classes
struct	Configuration
	Represents a configuration sent to the client. More...

struct	Props
	Properties. More...

Public Types
enum	MaskingCapabilities : UInt32
	Flags indicating the masks supported by the compositor. More...

enum	State
	Enumeration of possible blur states. More...

enum	ColorHint
	The background blur color hint. More...

enum	MaskType
	Mask types. More...

enum	PropChanges : UInt8
	Flags representing the property changes in propsChanged(). More...

Public Types inherited from LFactoryObject
enum class	Type : Int32
	Base factory object types. More...

Public Member Functions
	LBackgroundBlur (const void *params) noexcept
	Constructor.

	~LBackgroundBlur () noexcept=default
	Destructor.

Protocols::BackgroundBlur::RBackgroundBlur *	backgroundBlurResource () const noexcept
	Handle to the `lvr_background_blur` resource wrapper.

bool	supported () const noexcept
	Indicates whether the surface supports the protocol.

const Configuration &	pendingConfiguration () const noexcept
	Returns the last sent configuration parameters.

const Props &	props () const noexcept
	The current properties (acknowledged by the client).

State	state () const noexcept
	The current blur state.

ColorHint	colorHint () const noexcept
	The current blur color hint.

MaskType	maskType () const noexcept
	The current mask type.

const LRegion &	region () const noexcept
	Region in local surface coordinates to be blurred.

const LRRect &	roundRectMask () const noexcept
	Returns the current rounded rectangle mask, if the mask type is set to RoundRect .

const std::string &	svgPathMask () const noexcept
	Returns the current SVG path mask, if the mask type is set to SVGPath .

UInt32	serial () const noexcept
	Returns the last acknowledged configuration serial.

bool	isEmpty () const noexcept
	Indicates whether the blur region is empty.

bool	isFullSize () const noexcept
	Indicates whether the blur region covers the entire surface.

bool	visible () const noexcept
	Indicates whether the blur effect should be displayed.

void	configureState (State state) noexcept
	Notifies the client of the blur state.

void	configureColorHint (ColorHint hint) noexcept
	Notifies the client of the background color tone.

virtual void	configureRequest ()
	Triggered when the client creates a background blur resource for the surface.

virtual void	propsChanged (LBitset< PropChanges > changes, const Props &prevProps)
	Notifies changes of the current properties.

LSurface *	surface () const noexcept
	Retrieves the associated surface.

Public Member Functions inherited from LFactoryObject
Type	factoryObjectType () const noexcept
	Gets the base factory object type.

Public Member Functions inherited from LObject
	LObject (const LObject &) noexcept
	Copy constructor.

LObject &	operator= (const LObject &) noexcept
	Assignment operator (each object has its own individual LWeak reference count).

void	setUserData (UIntPtr data) const noexcept
	Store an unsigned integer value/pointer.

UIntPtr	userData () const noexcept
	Retrieves the stored unsigned integer value/pointer.

Static Public Attributes
static LBitset< MaskingCapabilities >	maskingCapabilities { NoMaskCap }
	Current masking capabilities of the compositor.

Additional Inherited Members
Protected Member Functions inherited from LObject
	LObject () noexcept=default
	Constructor of the LObject class.

virtual	~LObject () noexcept
	Destructor of the LObject class.

void	notifyDestruction () noexcept
	Notifies the object destruction.

Detailed Description

Background blur controller for surfaces.

This class allows configuring the background blur effect for a surface and listening to client changes. See LSurface::backgroundBlur().

When a client wants to apply a blur effect to a surface:

The configureRequest() is triggered, typically before the surface is mapped.
The compositor configures the blur state and color hint.
The client specifies the region to blur and may optionally apply an additional clipping mask.
The client acknowledges and commits the changes, which are notified via propsChanged().

The final blur region is determined by the intersection of the surface bounds, the region(), and the optional clipping mask.

The compositor can modify the state and color hint configuration at any time but should always wait for the client’s acknowledgment before applying the changes.

Compositors may support different masking capabilities depending on their rendering features. Modify maskingCapabilities to advertise the supported capabilities to clients.

Note: The SVG path and background blur protocols are experimental and thus not enabled by default in LCompositor::createGlobalsRequest().

Class Documentation

◆ Louvre::LBackgroundBlur::Configuration

struct Louvre::LBackgroundBlur::Configuration

Represents a configuration sent to the client.

Class Members
State	state { Disabled }	The desired blur state.
ColorHint	colorHint { Unknown }	The current blur color hint.
UInt32	serial { 0 }	The serial number associated with the configuration.

◆ Louvre::LBackgroundBlur::Props

struct Louvre::LBackgroundBlur::Props

Properties.

Class Members
State	state { Disabled }	The current blur state.
ColorHint	colorHint { Unknown }	The current blur color hint.
MaskType	maskType { NoMask }	The mask type.
LRegion	region { LRegion() }	The region to be blurred.
LRRect	roundRectMask	The rounded rectangle mask (if applicable)
string	svgPathMask	The SVG path mask (if applicable)
UInt32	serial { 0 }	The serial number associated with the configuration.
bool	isEmpty { true }	Whether the region is empty.
bool	isFullSize { false }	Whether the region covers the full surface.

Member Enumeration Documentation

◆ MaskingCapabilities

enum MaskingCapabilities : UInt32

Flags indicating the masks supported by the compositor.

These flags are used in maskingCapabilities .

Enumerator
NoMaskCap	No masking capability is supported.
RoundRectMaskCap	Supports rounded rectangle masking.
SVGPathMaskCap	Supports masking using an SVG path.

◆ State

enum State

Enumeration of possible blur states.

Enumerator
Disabled	Background blur is disabled (default).
Enabled	Background blur is enabled.

◆ ColorHint

enum ColorHint

The background blur color hint.

Enumerator
Unknown	Unknown (default).
Dark	Dark.
Light	Light.

◆ MaskType

enum MaskType

Mask types.

Enumerator
NoMask	No mask is applied (default).
RoundRect	A rounded rectangle mask is applied.
SVGPath	An SVG path is used as the mask.

◆ PropChanges

enum PropChanges : UInt8

Flags representing the property changes in propsChanged().

Enumerator
StateChanged	Indicates that the state has changed.
ColorHintChanged	Indicates that the color hint has changed.
RegionChanged	Indicates that the region has changed.
MaskChanged	Indicates that the clipping mask has changed.
SerialChanged	Indicates that the serial has changed.

Constructor & Destructor Documentation

◆ LBackgroundBlur()

LBackgroundBlur ( const void * params )

noexcept

Constructor.

Parameters

params Internal parameters provided in LCompositor::createObjectRequest().

◆ ~LBackgroundBlur()

~LBackgroundBlur ( )

defaultnoexcept

Destructor.

Member Function Documentation

◆ backgroundBlurResource()

Protocols::BackgroundBlur::RBackgroundBlur * backgroundBlurResource ( ) const

noexcept

Handle to the lvr_background_blur resource wrapper.

Returns: nullptr if the protocol is not supported()

◆ supported()

bool supported ( ) const

inlinenoexcept

Indicates whether the surface supports the protocol.

Note: If the client stops using the protocol, props() reverts to the default values, triggering propsChanged() when applicable.

◆ pendingConfiguration()

const Configuration & pendingConfiguration ( ) const

inlinenoexcept

Returns the last sent configuration parameters.

If the serial is equal to the current serial(), it means there is no pending configuration.

◆ props()

const Props & props ( ) const

inlinenoexcept

The current properties (acknowledged by the client).

The property values can also be accessed directly via aliases such as state(), colorHint(), maskType(), etc.

◆ state()

State state ( ) const

inlinenoexcept

The current blur state.

◆ colorHint()

ColorHint colorHint ( ) const

inlinenoexcept

The current blur color hint.

◆ maskType()

MaskType maskType ( ) const

inlinenoexcept

The current mask type.

◆ region()

const LRegion & region ( ) const

inlinenoexcept

Region in local surface coordinates to be blurred.

It is guaranteed that the region does not extend beyond the surface bounds.

◆ roundRectMask()

const LRRect & roundRectMask ( ) const

inlinenoexcept

Returns the current rounded rectangle mask, if the mask type is set to RoundRect .

The rounded rectangle is guaranteed to be valid, but it may extend beyond the surface bounds.

If the compositor does not support rounded rectangle masks, it should remove the RoundRectMaskCap from maskingCapabilities to prevent clients from using it.

◆ svgPathMask()

const std::string & svgPathMask ( ) const

inlinenoexcept

Returns the current SVG path mask, if the mask type is set to SVGPath .

Note that the path may extend beyond the surface bounds.

Warning: Louvre does not validate the SVG commands within the string. It is the responsibility of the caller to ensure the SVG path is valid.

If the compositor does not support SVG path masks, it should remove the SVGPathMaskCap from maskingCapabilities to prevent clients from using it.

◆ serial()

UInt32 serial ( ) const

inlinenoexcept

Returns the last acknowledged configuration serial.

◆ isEmpty()

bool isEmpty ( ) const

inlinenoexcept

Indicates whether the blur region is empty.

Equivalent to region().empty().

◆ isFullSize()

bool isFullSize ( ) const

inlinenoexcept

Indicates whether the blur region covers the entire surface.

Returns true if region() contains a single rectangle matching the current surface bounds.

◆ visible()

bool visible ( ) const

inlinenoexcept

Indicates whether the blur effect should be displayed.

The effect should be applied when the client has acknowledged an Enabled state and the blur region() is not empty.

◆ configureState()

void configureState ( State state )

inlinenoexcept

Notifies the client of the blur state.

This is an asynchronous operation. The current state should be maintained until the client acknowledges the change via propsChanged().

The configuration is immediately stored in pendingConfiguration().

If blur is not supported() calling this function is a no-op.

◆ configureColorHint()

void configureColorHint ( ColorHint hint )

inlinenoexcept

Notifies the client of the background color tone.

Clients can use this hint, for example, to set the overlay text color to white when the colorHint is Dark, and to black when it is Light.

This is an asynchronous operation. The current color hint should be maintained until the client acknowledges the change via propsChanged().

The configuration is immediately stored in pendingConfiguration().

If blur is not supported() calling this function is a no-op.

◆ configureRequest()

virtual void configureRequest ( )

virtual

Triggered when the client creates a background blur resource for the surface.

The compositor should respond by configuring both the blur state and color hint. If no configuration is explicitly sent, Louvre will automatically apply the current pending configuration values, which default to Disabled for the state and Unknown for the color hint.

Default implementation

void LBackgroundBlur::configureRequest()
{
    /* Example
 
    configureState(Enabled);
    configureColorHint(Light); */
}

◆ propsChanged()

virtual void propsChanged	(	LBitset< PropChanges >	changes,
		const Props &	prevProps
	)

virtual

Notifies changes of the current properties.

Triggered when the client acknowledges and commits a configuration, or when it requests a change.

Parameters

changes	A bitset indicating which properties have changed.
prevProps	The state of the properties before the change.

Default implementation

void LBackgroundBlur::propsChanged(LBitset<PropChanges> changes, const Props &prevProps)
{
    L_UNUSED(changes)
    L_UNUSED(prevProps)
}

◆ surface()

LSurface * surface ( ) const

inlinenoexcept

Retrieves the associated surface.

Member Data Documentation

◆ maskingCapabilities

LBitset<MaskingCapabilities> maskingCapabilities { NoMaskCap }

inlinestatic

Current masking capabilities of the compositor.

Defines the masking features currently supported by the compositor. This value should ideally be set during compositor initialization.

Modifying this value does not affect the masking capabilities announced to clients that have previously created background blur effects.

Note: This setting applies globally.

Classes

Public Types

Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Class Documentation

◆ Louvre::LBackgroundBlur::Configuration

◆ Louvre::LBackgroundBlur::Props

Member Enumeration Documentation

◆ MaskingCapabilities

◆ State

◆ ColorHint

◆ MaskType

◆ PropChanges

Constructor & Destructor Documentation

◆ LBackgroundBlur()

◆ ~LBackgroundBlur()

Member Function Documentation

◆ backgroundBlurResource()

◆ supported()

◆ pendingConfiguration()

◆ props()

◆ state()

◆ colorHint()

◆ maskType()

◆ region()

◆ roundRectMask()

◆ svgPathMask()

◆ serial()

◆ isEmpty()

◆ isFullSize()

◆ visible()

◆ configureState()

◆ configureColorHint()

◆ configureRequest()

Default implementation

◆ propsChanged()

Default implementation

◆ surface()

Member Data Documentation

◆ maskingCapabilities