Struct Renderer 

pub struct Renderer<'a> { /* private fields */ }

A cursor on a plane.

Borrows the device: the buffers and the framebuffers registered for them belong to it, and outliving it would leave this holding ids the kernel has recycled.

Implementations

impl<'a> Renderer<'a>

pub fn create( device: &'a Device, registry: &PlaneRegistry, config: &RendererConfig, ) -> Result<Self, CursorError>

Set up a cursor on config.crtc_id.

Chooses a plane, settles a buffer size by asking the kernel what it will take, and allocates. No cursor is loaded yet.

Errors

• CursorError::NoPlane or CursorError::PlaneUnusable from select_plane.
• CursorError::Unsupported on the legacy path, if config.rotation is not Rotation::None or the CRTC refuses a cursor – no cursor hardware, so composite one instead.
• CursorError::Io if a buffer cannot be allocated or the plane’s properties cannot be read, or, on the legacy path, if the caller is not DRM master.

pub const fn plane(&self) -> SelectedPlane

The plane this is drawing on.

pub const fn reserved_plane_id(&self) -> u32

The plane the cursor occupies, for a caller keeping its own commits off it: the plane it draws on on the atomic paths; on the legacy path, the CRTC’s cursor plane the kernel drives when RendererConfig::prefer_legacy chose the legacy ioctls over it, else 0.

pub const fn size(&self) -> (u32, u32)

The size of the cursor buffer, in pixels.

pub fn set_rotation(&mut self, rotation: Rotation) -> Result<(), CursorError>

Change which way up the cursor is, redrawing it.

Errors

• CursorError::Unsupported for any rotation but Rotation::None on PlanePath::Legacy, leaving the cursor as it was. drmModeSetCursor has nowhere to put one, as at Renderer::create, and the reference refuses here too.
• CursorError::Io if the buffer cannot be mapped.

pub fn set_cursor(&mut self, cursor: Cursor) -> Result<(), CursorError>

Load a cursor and draw its first frame.

Errors

CursorError::Io if the buffer cannot be mapped.

pub const fn move_to(&mut self, x: i32, y: i32)

Move the pointer.

pub const fn set_visible(&mut self, visible: bool)

Show or hide the cursor without unloading it.

pub fn prepare(&mut self) -> Result<bool, CursorError>

Bring the buffer up to date with the pointer’s position.

Near the top or left edge of the CRTC the sprite is drawn moved up and left inside its buffer, so the plane starts at the edge rather than off it: some drivers refuse a negative position (drm-cxx#384). A move into or out of that band, or within it, redraws the current frame. Renderer::commit calls this; a caller coalescing through Renderer::stage_into calls it first. Skipped, the commit carries the negative position, as before.

Returns whether the buffer changed.

Errors

CursorError::Io if the buffer cannot be mapped.

pub fn tick(&mut self, elapsed: Duration) -> Result<bool, CursorError>

Advance an animation, drawing a new frame if one is due.

Returns whether the buffer changed, so a caller can skip a commit that would publish the same pixels. A static cursor never changes.

Errors

CursorError::Io if the buffer cannot be mapped.

pub fn stage_into( &self, request: &mut AtomicRequest, ) -> Result<usize, CursorError>

Write the cursor’s current state into request.

For coalescing with the rest of a frame. The caller calls Renderer::prepare first, commits, and calls Renderer::published afterwards.

Errors

CursorError::MissingProperty if the plane lacks a required property – always, on PlanePath::Legacy, which has no plane to stage: use Renderer::commit there.

pub const fn published(&mut self)

Note that a commit carrying Renderer::stage_into’s writes landed.

See PingPong::published for what happens when it did not.

pub fn commit(&mut self) -> Result<(), CursorError>

Stage and commit on their own.

For callers with nothing to coalesce with. A compositor should prefer Renderer::stage_into.

Errors

CursorError::MissingProperty from staging, or CursorError::Io if the kernel refuses the commit.

pub fn pause(self) -> Paused

Give up the device for a session pause.

See Paused for what is released and what cannot be.

Trait Implementations

impl<'a> Debug for Renderer<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Renderer<'_>

fn drop(&mut self)

Take the cursor off the CRTC, as the reference’s destructor does, so the next client does not inherit the sprite.

Only once something was installed: a plane the kernel never saw this use can refuse being cleared. On the legacy path, freeing the buffers does not do it – the kernel holds its own reference to the cursor’s framebuffer – so without this the sprite stays on screen.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.