Struct PlacementIteration 

pub struct PlacementIteration<'t, 'alloc>(/* private fields */);

Available on crate feature kitty-graphics only.

Obtained via PlacementIterator::update. The reference is borrowed from the storage with lifetime 't and remains valid until the next mutating terminal call.

Implementations

impl<'t, 'alloc> PlacementIteration<'t, 'alloc>

pub fn next(&mut self) -> Option<&Self>

Advance the placement iterator to the next placement.

If a layer filter has been set via PlacementIteration::set_layer, only placements matching that layer are returned.

pub fn set_layer(&self, layer: Layer) -> Result<()>

Set the z-layer filter for the iterator.

pub fn pixel_size( &self, image: &Image<'t>, terminal: &'t Terminal<'_, '_>, ) -> Result<PixelSize>

Compute the rendered pixel size of the current placement.

Takes into account the placement’s source rectangle, specified columns/rows, and aspect ratio to calculate the final rendered pixel dimensions.

pub fn grid_size( &self, image: &Image<'t>, terminal: &'t Terminal<'_, '_>, ) -> Result<GridSize>

Compute the rendered pixel size of the current placement.

Takes into account the placement’s source rectangle, specified columns/rows, and aspect ratio to calculate the final rendered pixel dimensions.

pub fn viewport_pos( &self, image: &Image<'t>, terminal: &'t Terminal<'_, '_>, ) -> Result<Option<ViewportPos>>

Get the viewport-relative grid position of the current placement.

Converts the placement’s internal pin to viewport-relative column and row coordinates. The returned coordinates represent the top-left corner of the placement in the viewport’s grid coordinate space.

The row value can be negative when the placement’s origin has scrolled above the top of the viewport. For example, a 4-row image that has scrolled up by 2 rows returns row=-2, meaning its top 2 rows are above the visible area but its bottom 2 rows are still on screen. Embedders should use these coordinates directly when computing the destination rectangle for rendering; the embedder is responsible for clipping the portion of the image that falls outside the viewport.

Returns None when the placement is completely outside the viewport (its bottom edge is above the viewport or its top edge is at or below the last viewport row), or when the placement is a virtual (unicode placeholder) placement.

pub fn source_rect(&self, image: &Image<'t>) -> Result<SourceRect>

Get the resolved source rectangle for the current placement.

Applies kitty protocol semantics: a width or height of 0 in the placement means “use the full image dimension”, and the resulting rectangle is clamped to the actual image bounds. The returned values are in pixels and are ready to use for texture sampling.

pub fn rect( &self, image: &Image<'t>, terminal: &'t Terminal<'_, '_>, ) -> Result<Selection<'t>>

Get the resolved source rectangle for the current placement.

Applies kitty protocol semantics: a width or height of 0 in the placement means “use the full image dimension”, and the resulting rectangle is clamped to the actual image bounds. The returned values are in pixels and are ready to use for texture sampling.

pub fn placement_render_info( &self, image: &Image<'t>, terminal: &'t Terminal<'_, '_>, ) -> Result<PlacementRenderInfo>

Get all rendering geometry for a placement in a single call.

Combines pixel size, grid size, viewport position, and source rectangle into one struct.

When viewport_visible is false, the placement is fully off-screen or is a virtual placement; viewport_col and viewport_row may contain meaningless values in that case.

pub fn image_id(&self) -> Result<u32>

The image ID this placement belongs to.

pub fn placement_id(&self) -> Result<u32>

The image ID this placement belongs to.

pub fn is_virtual(&self) -> Result<bool>

Whether this is a virtual placement (unicode placeholder).

pub fn x_offset(&self) -> Result<u32>

Pixel offset from the left edge of the cell.

pub fn y_offset(&self) -> Result<u32>

Pixel offset from the top edge of the cell.

pub fn source_x(&self) -> Result<u32>

Source rectangle x origin in pixels.

pub fn source_y(&self) -> Result<u32>

Source rectangle y origin in pixels.

pub fn source_width(&self) -> Result<u32>

Source rectangle width in pixels (0 = full image width).

pub fn source_height(&self) -> Result<u32>

Source rectangle height in pixels (0 = full image height).

pub fn columns(&self) -> Result<u32>

Number of columns this placement occupies.

pub fn rows(&self) -> Result<u32>

Number of rows this placement occupies.

pub fn z(&self) -> Result<i32>

Z-index for this placement.

Trait Implementations

impl<'t, 'alloc> Debug for PlacementIteration<'t, 'alloc>

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

Formats the value using the given formatter.