Content Operations

Content Operations

PDF pages are rendered by a sequence of operators stored in a content stream. Aspose.PDF FOSS for .NET exposes these operators through OperatorCollection on each Page, and provides ContentStreamBuilder for constructing new content programmatically.

Reading content-stream operators

Every Page has a Contents property that returns an OperatorCollection. Iterate it to inspect each operator.

using var doc = Document.Open(pdfBytes);
var page = doc.Pages[1];

foreach (var op in page.Contents)
{
    Console.WriteLine(op.ToString());
}

Building content streams

ContentStreamBuilder provides a fluent API for constructing content-stream operator sequences including graphics-state management, path construction, text output, and color settings.

var builder = new ContentStreamBuilder();
builder.SaveState();
builder.SetFillColor(1.0, 0.0, 0.0);  // Red fill
builder.SetMatrix(1, 0, 0, 1, 72, 700); // Translate
// ... add drawing or text operators
builder.RestoreState();

Graphics state

GraphicsState tracks the current transformation matrix, text state, and color values as operators execute. Key operations:

var gs = new GraphicsState();
gs.Save();
gs.ConcatMatrix(new Matrix(1, 0, 0, 1, 100, 200));
gs.Restore();

Color operators

SetColor and SetColorStroke set fill and stroke colors respectively. They accept RGB, CMYK, or grayscale components.

// RGB fill color (blue)
var fill = new SetColor(0, 0, 1);

// RGB stroke color (red)
var stroke = new SetColorStroke(1, 0, 0);

Text operators

ShowText renders a text string at the current text position using the current font and size from the graphics state.

var textOp = new ShowText("Hello, PDF!");

SetTextMatrix positions text by defining a transformation matrix for text space.

Extended graphics state

ExtGState controls advanced rendering properties like fill and stroke alpha (transparency) and blend mode.

Tips and Best Practices

• Always pair SaveState / RestoreState (or q / Q operators) to avoid corrupting the graphics state stack.
• Use ContentStreamBuilder for new content rather than manually constructing operator objects.
• Inspect OperatorCollection read-only before modifying — unexpected operator sequences can cause rendering issues.
• Color operators must match the current color space (RGB, CMYK, or grayscale).
• Use SetAdvancedColor for pattern and ICC-based color spaces.

Common Issues

FAQ

What is a PDF content stream?

A content stream is a sequence of operators that describe how to render a page — drawing paths, placing text, setting colors, and managing graphics state.

Can I add new content to an existing page?

Yes. Access page.Contents and add new operators, or use ContentStreamBuilder to construct a sequence and append it.

How do I make text transparent?

Use ExtGState to set the fill alpha (ca) to a value between 0 (fully transparent) and 1 (fully opaque).

API Reference Summary

See Also

• Aspose.PDF for .NET Enterprise Product