svg2pdf

Supported

• Paths (simple and complex fills)
• Gradients
• Patterns
• Clip paths and Masks
• Transformations
• Viewbox
• Text
• Raster images and nested SVGs

Unsupported

• spreadMethod attribute in gradients
• Color management for raster images (uses PDF's DeviceRGB space)
• Many SVG2 features

The svg2pdf engine manages the complexity of SVG styles by explicitly separating the filling and stroking phases of a path. This is necessary to support:

• Different Paint Orders: Respecting PaintOrder::FillAndStroke vs PaintOrder::StrokeAndFill.
• Advanced Fills/Strokes: Correctly applying opacities to patterns, linear gradients, or radial gradients.
• Opacity Management: Ensuring that a stroke opacity of 0.5 applied to a pattern affects the whole pattern correctly rather than just the individual elements within the pattern.

The PageOptions struct controls the physical properties of the resulting PDF page. Currently, it only supports setting the DPI (Dots Per Inch).

let page_options = PageOptions {
    dpi: 300.0,
};

The ConversionOptions struct allows you to fine-tune how the SVG is translated to PDF content.

let options = ConversionOptions {
    compress: true,
    raster_scale: 2.0,
    embed_text: true,
    pdfa: false,
};

Use create_shading_soft_mask to generate a luminosity-based soft mask that renders the opacity of gradient stops as grayscale shading.

This is required when a gradient's stops have an opacity value less than 1.0. If all stops are fully opaque, the function returns None and no mask is created.

Note: This function relies on the bbox (bounding box) of the element to define the mask area.

create_shading_soft_mask(
    paint: &Paint,
    chunk: &mut Chunk,
    ctx: &mut Context,
    bbox: Rect,
) -> Option<Ref

The render function converts an SVG Mask into a PDF content stream. It creates a mask object reference, adds it to the ResourceContainer as a graphics state, and applies that state to the current PDF content stream using set_parameters.

pub fn render(
    group: &Group,
    mask: &Mask,
    chunk: &mut Chunk,
    content: &mut Content,
    ctx: &mut Context,
    rc: &mut ResourceContainer,
) -> Result<()>

Use create_shading_pattern to convert a usvg::Paint (specifically linear or radial gradients) into a PDF shading pattern object.

Note: This function ignores stop opacities. If your gradient contains stops with transparency (opacity < 1.0), you must also call create_shading_soft_mask to handle the transparency correctly.

create_shading_pattern(
    paint: &Paint,
    chunk: &mut Chunk,
    ctx: &mut Context,
    accumulated_transform: &Transform,
) -> Ref

Use tree_to_xobject to convert a usvg::Tree into a PDF XObject (similar to an image). This is useful for embedding SVG content as a reusable, sized object within a PDF.

Key behaviors:

• It calculates the bounding box based on the tree size.
• It applies a scaling matrix to fit the content into a 1x1 coordinate space.
• If ctx.options.compress is enabled, it applies the Filter::FlateDecode to the XObject.
• It manages resource allocation and finishing via the provided Context and a new ResourceContainer.

let x_ref = tree_to_xobject(
    tree,  // &usvg::Tree
    chunk, // &mut pdf_writer::Chunk
    ctx,   // &mut Context
)?;
// Returns a pdf_writer::Ref to the created XObject

The finish_content method handles the finalization of a pdf_writer::Content object. It automatically respects the compress setting within your ConversionOptions:

• If options.compress is true, the content is deflated (compressed) before being returned.
• If options.compress is false, the raw content is returned as a Vec<u8>.

// 'ctx' is your Context instance
// 'content' is a pdf_writer::Content object
let final_bytes = ctx.finish_content(content);

The create function generates a new PDF mask object (XObject) from an SVG Mask.

Key behaviors:

• It handles nested masks recursively.
• It applies a clip path to the mask's bounding rectangle to ensure compatibility with browsers (like Firefox) that may misinterpret bounding boxes under certain transforms.
• It applies FlateDecode compression if ctx.options.compress is enabled.
• It configures the XObject with standard transparency settings (non-isolated, no knockout) and sets the color space to the context's sRGB reference.
• It returns a Ref to a new graphics state that uses this mask as a soft_mask with the appropriate PDF mask subtype.

pub fn create(
    parent: &Group,
    mask: &Mask,
    chunk: &mut Chunk,
    ctx: &mut Context,
) -> Result<Ref>