skia-rs: Instructions file for Codex

Cursor rule: .cursor/rules/api-design.mdc

API design principles and patterns for skia-rs

Applies to: ["**/*.rs"]

API Design Principles

Skia API Compatibility

The primary goal is API compatibility with Skia. When implementing a feature:

1. Reference the original: Check skia/ submodule for the C++ implementation
2. Match signatures: Function names and parameter order should match Skia
3. Match semantics: Behavior should be identical to Skia
4. Document differences: If Rust requires a different approach, document it

Builder Pattern

Use builders for complex object construction:

pub struct PathBuilder {
    path: Path,
    last_move: Option<Point>,
}

impl PathBuilder {
    pub fn new() -> Self { ... }
    pub fn move_to(&mut self, x: Scalar, y: Scalar) -> &mut Self { ... }
    pub fn line_to(&mut self, x: Scalar, y: Scalar) -> &mut Self { ... }
    pub fn build(self) -> Path { ... }
}

Method Chaining

Support fluent interfaces where appropriate:

impl Paint {
    pub fn set_color(&mut self, color: Color4f) -> &mut Self {
        self.color = color;
        self
    }

    pub fn set_style(&mut self, style: Style) -> &mut Self {
        self.style = style;
        self
    }
}

// Usage:
paint.set_color(Color4f::RED)
     .set_style(Style::Stroke)
     .set_stroke_width(2.0);

Const Correctness

• Use const fn where possible
• Define common constants as associated constants

impl Rect {
    pub const EMPTY: Self = Self { left: 0.0, top: 0.0, right: 0.0, bottom: 0.0 };

    #[inline]
    pub const fn new(left: Scalar, top: Scalar, right: Scalar, bottom: Scalar) -> Self {
        Self { left, top, right, bottom }
    }
}

Common Patterns

Cloning vs Referencing

• Prefer references for read-only access
• Clone only when ownership transfer is needed
• Use Cow<T> when clone-on-write is beneficial

Option Patterns

// Skia-style: return Option for fallible operations
pub fn invert(&self) -> Option<Matrix> {
    let det = self.determinant();
    if det == 0.0 {
        return None;
    }
    Some(self.compute_inverse(det))
}