PDF Graphics .NET :: Help :: Painting graphics :: Images and stencils

Images and stencils

This section covers the following topics:

Images

To create an image, use the Image class and supply a path to a file containing the image. The file is then parsed to determine the image's dimensions and other properties required to render the image.

Drawing images onto a graphics surface is done through a single method call on the Graphics instance, DrawImage. This method accepts an image and a destination rectangle to draw the image into. This rectangle determines the size of the image on the page as well as its location. Images that are not originally of the same size as the destination rectangle will be scaled.

Image myImage = new Image("Kitten.jpg"); g.DrawImage(myImage, new Rectangle(10, 10, 100, 100)); g.DrawImage(myImage, new Rectangle(10, 120, 100, 100));

In the example above, an image is created based on the file Kitten.jpg. It is then drawn onto the page twice.

Images are embedded into the PDF document. It is therefore advised not to use excessively large images as this will increase the size of the output PDF. If an image is drawn twice or more onto a page, or across pages, it will be embedded only once. Creating multiple Image instances with the same path will also cause the image to be embedded only once, and reused across the instances. For example:

Image myImage = new Image("Kitten.jpg"); g.DrawImage(myImage, new Rectangle(10, 10, 100, 100)); g.NewPage(); Image second = new Image("Kitten.jpg"); g.DrawImage(second, new Rectangle(10, 10, 100, 100));

The resulting PDF file will contain the Kitten.jpg file only once.

The only image file format currently supported by PDF Graphics .NET is the JFIF (.jpg) format. A file that is not recognised as a JFIF file will be refused.

Stencils

A stencil is a reusable graphic that is defined once and used once or more times across a document. Stencils can use any graphic primitive that a PDF page supports, including further stencils. To create a stencil, use the CreateStencil method on the Graphics class. To paint contents onto a stencil surface, use the Graphics property of the Stencil instance.

Painting a stencil is done through the DrawStencil method of the Graphics class. This works for pages as well as for stencils themselves. See the following example:

GraphicsPath path = new GraphicsPath(); path.AddLine( 0.0f, 0.0f, 6.0f, 12.0f); path.AddLine( 6.0f, 12.0f, 19.0f, 13.8f); path.AddLine( 19.0f, 13.8f, 9.7f, 23.2f); path.AddLine( 9.7f, 23.2f, 12.0f, 36.0f); path.AddLine( 12.0f, 36.0f, 0.0f, 30.0f); path.AddLine( 0.0f, 30.0f, -11.6f, 36.4f); path.AddLine(-11.6f, 36.4f, -9.4f, 23.0f); path.AddLine( -9.4f, 23.0f, -19.0f, 13.8f); path.AddLine(-19.0f, 13.8f, -6.0f, 12.0f); path.Close(); Stencil star = g.CreateStencil(40, 40); star.Graphics.FillPath(Rgb.YellowBrush, path, 20, 0); star.Graphics.DrawPath(Rgb.RedPen, path, 20, 0); g.DrawStencil(star, 40, 40); g.DrawStencil(star, 70, 80); g.DrawStencil(star, 20, 100);

The above code defines a stencil with a yellow filled star graphic, and paints it three times onto a page:

Stencils can contain other stencils. Practicality aside, there is no limit to the levels of nesting. Using the star stencil used in the example, above, the following example creates a new stencil that is composed of a ring of stars.

Stencil ring = g.CreateStencil(400, 400); ring.Graphics.TransformTranslate(200, 200); double increment = Math.PI / 6f; for (double angle = 0; angle < Math.PI * 2; angle += increment) { ring.Graphics.DrawStencil( star, (float)Math.Cos(angle) * 150f, (float)Math.Sin(angle) * 150); } g.DrawStencil(ring, 100, 100);

Notes

Navigation options:

< Text, fonts and text styles | Transformations >