Struct Shape 

pub struct Shape<'eng> { /* private fields */ }

A two-dimensional shape with path, fill, and stroke properties.

The lifetime 'eng ties this shape to a Thorvg engine instance, ensuring the engine cannot be terminated while the shape exists. Create shapes via Thorvg::shape().

Implementations

impl Shape<'_>

pub fn reset(&mut self) -> Result<()>

Resets the shape’s path, clearing all sub-paths.

Color, fill, and stroke properties are retained. The path-data storage is kept allocated for reuse rather than freed.

pub fn move_to(&mut self, x: f32, y: f32) -> Result<()>

Begins a new sub-path at (x, y), setting the current point.

pub fn line_to(&mut self, x: f32, y: f32) -> Result<()>

Draws a line from the current point to (x, y).

If this is the first command in the path it behaves like move_to. The current point becomes (x, y).

pub fn cubic_to( &mut self, cx1: f32, cy1: f32, cx2: f32, cy2: f32, x: f32, y: f32, ) -> Result<()>

Draws a cubic Bézier curve from the current point to (x, y).

(cx1, cy1) and (cx2, cy2) are the first and second control points. The current point becomes (x, y).

pub fn close(&mut self) -> Result<()>

Closes the current sub-path with a line back to its start point.

The current point is reset to that start point. Has no effect if the sub-path contains no points.

pub fn append_path(&mut self, path: &Path) -> Result<()>

Appends a sub-path described by a typed Path.

Closes the round-trip with path: a value returned by that getter can be re-applied here verbatim. Commands are translated through PathCommand::to_raw and points are repacked as Tvg_Point for the C call. Both translations allocate a temporary Vec; the original Path is left intact.

ThorVG’s C-side path builder reads points lock-step with commands according to PathCommand::points_consumed. If the points vector does not supply exactly as many points as the commands require, the sub-path is appended but the shape does not render — this is not reported as an error. Constructing such a Path is permitted on the Rust side.

Errors

Returns Error::InvalidArguments if either commands or points is empty.

pub fn path(&self) -> Result<Path>

Returns the shape’s current path data.

The result bundles the command and point buffers as a single Path value; walk it with Path::segments to receive typed Segments instead of managing a separate points cursor.

Allocates two Vecs; for the cheap “how big is it?” query use path_counts instead, which passes null for the data pointers and avoids the copy.

Unknown command bytes from the C side (none are expected for a thorvg-built shape) are dropped silently while keeping the points buffer intact, which keeps Path::segments from desynchronising.

pub fn path_counts(&self) -> Result<(u32, u32)>

Returns (commands_count, points_count) for the shape’s current path without copying the buffers.

Cheaper than path when only the sizes are needed (passes null for the data pointers, matching the pre-typed-path Rust signature).

pub fn append_rect(&mut self, rect: Rect) -> Result<()>

Appends a rectangle (optionally rounded) to the path.

Starts a new sub-path; it is not connected to the previous one. See Rect for the parameter layout. When rx and ry each reach or exceed half the width and half the height respectively, the rounded rectangle degenerates into an ellipse.

pub fn append_circle(&mut self, circle: Circle) -> Result<()>

Appends an ellipse to the path.

Starts a new sub-path; it is not connected to the previous one. See Circle for the parameter layout — Circle::new for true circles, Circle::ellipse for elliptical shapes.

pub fn set_fill_color(&mut self, color: Rgba) -> Result<()>

Sets the shape’s solid fill color.

Each channel is in the range 0..=255; a of 0 is fully transparent and 255 fully opaque. A shape carries either a solid fill or a gradient fill — whichever was set last wins, so this overrides any gradient set via set_linear_gradient / set_radial_gradient.

pub fn fill_color(&self) -> Result<Rgba>

Returns the shape’s solid fill color.

Defaults to fully transparent black (0, 0, 0, 0) on a freshly created shape.

pub fn set_fill_rule(&mut self, rule: FillRule) -> Result<()>

Sets the fill rule.

Determines how the interior is computed when the path self-intersects. The engine default is FillRule::NonZero.

pub fn fill_rule(&self) -> Result<FillRule>

Returns the current fill rule.

pub fn set_linear_gradient(&mut self, grad: LinearGradient<'_>) -> Result<()>

Sets a linear gradient fill, taking ownership of grad.

Overrides any solid color set via set_fill_color: a shape carries either a solid fill or a gradient fill, whichever was set last.

pub fn set_radial_gradient(&mut self, grad: RadialGradient<'_>) -> Result<()>

Sets a radial gradient fill, taking ownership of grad.

Overrides any solid color set via set_fill_color, as with set_linear_gradient.

pub fn gradient(&self) -> Result<Option<BorrowedGradient<'_>>>

Returns a read-only view of the shape’s fill gradient.

• Ok(None) — no gradient is set.
• Ok(Some(view)) — fill gradient present; the view discriminates linear vs radial at borrow time so subsequent reads are type-checked.
• Err(_) — the C side rejected the read or returned an unrecognised gradient kind.

The borrow lifetime is tied to &self; the shape owns the underlying gradient and frees it on its own teardown.

pub fn set_paint_order(&mut self, order: PaintOrder) -> Result<()>

Sets the rendering order of fill and stroke. See PaintOrder.

pub fn set_stroke_width(&mut self, width: f32) -> Result<()>

Sets the stroke width in pixels.

A width of 0.0 (the engine default) disables the stroke.

pub fn stroke_width(&self) -> Result<f32>

Returns the stroke width in pixels.

pub fn set_stroke_color(&mut self, color: Rgba) -> Result<()>

Sets the stroke’s solid color.

Each channel is in the range 0..=255. The stroke is invisible while the stroke width is 0.0 (the default), regardless of color. As with the fill, the stroke carries either a solid color or a gradient (set_stroke_linear_gradient / set_stroke_radial_gradient) — whichever was set last.

pub fn stroke_color(&self) -> Result<Rgba>

Returns the stroke’s solid color.

Errors

Returns Error::InsufficientCondition if no stroke has been set on the shape.

pub fn set_stroke_cap(&mut self, cap: StrokeCap) -> Result<()>

Sets the stroke line cap style.

The engine default is StrokeCap::Square.

pub fn stroke_cap(&self) -> Result<StrokeCap>

Returns the stroke line cap style.

pub fn set_stroke_join(&mut self, join: StrokeJoin) -> Result<()>

Sets the stroke line join style.

The engine default is StrokeJoin::Bevel.

pub fn stroke_join(&self) -> Result<StrokeJoin>

Returns the stroke line join style.

pub fn set_stroke_miterlimit(&mut self, miterlimit: f32) -> Result<()>

Sets the stroke miter limit.

Caps how far a StrokeJoin::Miter join may extend before it is converted to a bevel; ignored for other join styles. The engine default is 4.0.

Errors

Returns Error::InvalidArguments if miterlimit is negative.

pub fn stroke_miterlimit(&self) -> Result<f32>

Returns the stroke miter limit.

pub fn set_stroke_dash(&mut self, pattern: &[f32], offset: f32) -> Result<()>

Sets the stroke dash pattern.

pattern holds alternating dash and gap lengths; offset shifts the starting point within the repeating pattern. Negative entries are treated as 0.0, and if every entry is <= 0.0 the dash is ignored. An odd-length pattern is repeated once so dashes and gaps stay alternating.

Errors

Returns Error::InvalidArguments when pattern is empty: the engine rejects a non-null pointer paired with a count of zero, and a Rust empty slice yields exactly that. To clear an existing dash pattern, set a single-element pattern of 0.0 (which the engine then ignores) rather than passing an empty slice.

pub fn stroke_dash(&self) -> Result<(Vec<f32>, f32)>

Returns the stroke dash pattern and offset.

The pattern is empty when no dashing is set.

pub fn stroke_gradient(&self) -> Result<Option<BorrowedGradient<'_>>>

Returns a read-only view of the shape’s stroke gradient.

Same semantics as gradient, but for the stroke gradient configured via set_stroke_linear_gradient / set_stroke_radial_gradient.

pub fn set_stroke_linear_gradient( &mut self, grad: LinearGradient<'_>, ) -> Result<()>

Sets a linear gradient as the stroke fill.

Companion to set_linear_gradient on the fill side.

pub fn set_stroke_radial_gradient( &mut self, grad: RadialGradient<'_>, ) -> Result<()>

Sets a radial gradient as the stroke fill.

Companion to set_radial_gradient on the fill side. The underlying C call (tvg_shape_set_stroke_gradient) takes a polymorphic Tvg_Gradient, so both gradient kinds are accepted as a stroke fill.

pub fn set_trimpath( &mut self, begin: f32, end: f32, simultaneous: bool, ) -> Result<()>

Sets the visible segment of the path via trimming.

begin and end are normalised positions along the path, where 0.0 is the start and 1.0 the end. Values outside [0.0, 1.0] wrap around circularly (like angle wrapping) rather than being clamped.

When a shape has multiple sub-paths, simultaneous controls how they are trimmed. true (the engine default) applies the trim to every sub-path independently; false treats them as a single concatenated path whose total length is the sum of the individual lengths.

Trait Implementations

impl Debug for Shape<'_>

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

Formats the value using the given formatter.

impl Drop for Shape<'_>

fn drop(&mut self)

Executes the destructor for this type.

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.

impl Paint for Shape<'_>

fn raw(&self) -> Tvg_Paint

Returns the underlying raw Tvg_Paint handle without transferring ownership.

fn into_raw(self) -> Tvg_Paint

Consumes self and returns the raw handle, transferring ownership.

unsafe fn from_raw_paint(raw: Tvg_Paint) -> Self

Constructs a new owned instance from a raw Tvg_Paint handle.

fn set_opacity(&mut self, opacity: u8) -> Result<()>

Sets the opacity, where 0 is fully transparent and 255 is fully opaque.

fn opacity(&self) -> Result<u8>

Returns the opacity, in the range 0..=255.

fn set_visible(&mut self, visible: bool) -> Result<()>

Sets whether the paint is rendered.

fn visible(&self) -> bool

Returns true if the paint is rendered.

fn scale(&mut self, factor: f32) -> Result<()>

Scales the paint uniformly by factor.

fn rotate(&mut self, degree: f32) -> Result<()>

Rotates the paint by degree degrees, clockwise about the origin.

fn translate(&mut self, x: f32, y: f32) -> Result<()>

Translates the paint by (x, y).

fn set_transform(&mut self, m: &Matrix) -> Result<()>

Sets the affine transformation matrix, replacing any prior transform.

fn transform(&self) -> Result<Matrix>

Returns the affine transformation matrix.

fn bounds(&self) -> Result<(f32, f32, f32, f32)>

Returns the axis-aligned bounding box (x, y, width, height) in canvas space, with all transforms applied.

fn bounds_obb(&self) -> Result<[Point; 4]>

Returns the oriented bounding box (OBB) as its four corner points in canvas space.

fn set_clip(&mut self, clipper: Shape<'_>) -> Result<()>

Clips this paint’s drawing region to the clipper shape’s paths.

fn clip(&self) -> Option<Shape<'_>>

Returns the clip shape set via set_clip, or None if none is set.

fn set_mask<P: Paint>(&mut self, mask: P, method: MaskMethod) -> Result<()>

Masks this paint with mask using the given MaskMethod.

fn mask(&self) -> Option<(BorrowedPaint<'_>, MaskMethod)>

Returns the mask target and MaskMethod set via set_mask, or None if no mask is attached.

fn set_blend(&mut self, method: BlendMethod) -> Result<()>

Sets the BlendMethod used to composite this paint over the layer beneath it.

fn set_id(&mut self, id: u32) -> Result<()>

Sets the paint’s id, used to identify a paint instance within a scene.

fn id(&self) -> u32

Returns the user-assigned id, or 0 if none was set.

fn paint_type(&self) -> Result<PaintType>

Returns the concrete PaintType of this paint.

fn intersects(&self, x: i32, y: i32, w: i32, h: i32) -> bool

Returns true if the rectangle (x, y, w, h) intersects this paint’s filled area (hit-testing).

fn duplicate(&self) -> Option<Self>

where Self: Sized,

Returns a deep copy of this paint with all properties preserved, or None if duplication fails.

impl Send for Shape<'_>