PdfFreeTriangleMeshShading Class

Namespace:
GemBox.Pdf.Content.Patterns
Assembly:
GemBox.Pdf.dll

Type 4 shadings (free-form Gouraud-shaded triangle meshes) are commonly used to represent complex colored and shaded three-dimensional shapes. The area to be shaded is defined by a path composed entirely of triangles. The color at each vertex of the triangles is specified, and a technique known as Gouraud interpolation is used to color the interiors.

public sealed class PdfFreeTriangleMeshShading : PdfMeshShading, IEnumerable<PdfMeshTriangle>, IEnumerable
Public NotInheritable Class PdfFreeTriangleMeshShading
    Inherits PdfMeshShading
    Implements IEnumerable(Of PdfMeshTriangle), IEnumerable
Inheritance:
System.Object
PdfFreeTriangleMeshShading
Implements
System.Collections.Generic.IEnumerable<PdfMeshTriangle>
System.Collections.IEnumerable

Constructors

PdfFreeTriangleMeshShading(IList<PdfFunction>, PdfColorSpace)

Initializes a new instance of the PdfFreeTriangleMeshShading class with an optional ColorSpace.

The Add(PdfMeshVertex, PdfMeshVertex, PdfMeshVertex) overload must be used to populate a mesh with a new triangle, unconnected to any other. Subsequent, connected, triangles can be added with the Add(PdfMeshSharedEdge, PdfMeshVertex) overload.

If the function parameter is omitted or is null, then the PdfMeshVertex(Double, Double, PdfColor) constructor should be used for creating vertices; otherwise, the PdfMeshVertex(Double, Double, Double) constructor should be used. You can use the static method CreateFunction(IList<PdfShadingColor>) to create an interpolation function from two or more PdfShadingColors.

note

The Pack(Boolean) method must be used after the mesh is populated to resolve the values of the BitsPerCoordinate, BitsPerComponent, BitsPerFlag, and Decode entries and to serialize the mesh data to the underlying stream.

public PdfFreeTriangleMeshShading(IList<PdfFunction> function = null, PdfColorSpace colorSpace = null)
Public Sub New(function As IList(Of PdfFunction) = Nothing, colorSpace As PdfColorSpace = Nothing)
Parameters
function
System.Collections.Generic.IList<PdfFunction>

The optional value of the Function entry.

colorSpace
PdfColorSpace

The color space in which color values shall be expressed. If omitted, the DeviceRGB is used.

PdfFreeTriangleMeshShading(Int32, Int32, Int32, PdfNumberRange, PdfNumberRange, IList<PdfFunction>, PdfColorSpace)

Initializes a new instance of the PdfFreeTriangleMeshShading class that has the specified mesh data serialization settings and, optionally, ColorSpace.

The Add(PdfMeshVertex, PdfMeshVertex, PdfMeshVertex) overload must be used to populate a mesh with a new triangle, unconnected to any other. Subsequent, connected, triangles can be added with the Add(PdfMeshSharedEdge, PdfMeshVertex) overload.

If the function parameter is omitted or is null, then the PdfMeshVertex(Double, Double, PdfColor) constructor should be used for creating vertices; otherwise, the PdfMeshVertex(Double, Double, Double) constructor should be used. You can use the static method CreateFunction(IList<PdfShadingColor>) to create an interpolation function from two or more PdfShadingColors.

The Decode entry is set based on the decodeX, decodeY, and ranges of valid color component values specified by the Function's domain or ColorSpace. The Decode for color components can be subsequently updated (it starts with a PdfNumberRange at index 2 in the Decode entry).

public PdfFreeTriangleMeshShading(int bitsPerCoordinate, int bitsPerComponent, int bitsPerFlag, PdfNumberRange decodeX, PdfNumberRange decodeY, IList<PdfFunction> function = null, PdfColorSpace colorSpace = null)
Public Sub New(bitsPerCoordinate As Integer, bitsPerComponent As Integer, bitsPerFlag As Integer, decodeX As PdfNumberRange, decodeY As PdfNumberRange, function As IList(Of PdfFunction) = Nothing, colorSpace As PdfColorSpace = Nothing)
Parameters
bitsPerCoordinate
System.Int32

The number of bits used to represent each vertex coordinate. The value shall be 1, 2, 4, 8, 12, 16, 24, or 32.

bitsPerComponent
System.Int32

The number of bits used to represent each color component. The value shall be 1, 2, 4, 8, 12, or 16.

bitsPerFlag
System.Int32

The number of bits used to represent the edge flag for each vertex. The value of bitsPerFlag shall be 2, 4, or 8, but only the least significant 2 bits in each flag value shall be used.

decodeX
PdfNumberRange

A PdfNumberRange specifying how to map horizontal component of vertex coordinates into the appropriate range of values.

decodeY
PdfNumberRange

A PdfNumberRange specifying how to map vertical component of vertex coordinates into the appropriate range of values.

function
System.Collections.Generic.IList<PdfFunction>

The optional value of the Function entry.

colorSpace
PdfColorSpace

The color space in which color values shall be expressed. If omitted, the DeviceRGB is used.

Exceptions
System.ArgumentOutOfRangeException

bitsPerCoordinate is not 1, 2, 4, 8, 12, 16, 24, or 32.

System.ArgumentOutOfRangeException

bitsPerComponent is not 1, 2, 4, 8, 12, or 16.

System.ArgumentOutOfRangeException

bitsPerFlag is not 2, 4, or 8.

Properties

BitsPerFlag

(Required) The number of bits used to represent the edge flag for each vertex. The value of BitsPerFlag shall be 2, 4, or 8, but only the least significant 2 bits in each flag value shall be used. The value for the edge flag shall be 0, 1, or 2.

public int BitsPerFlag { get; }
Public ReadOnly Property BitsPerFlag As Integer
Property Value
System.Int32

The number of bits used to represent the edge flag for each vertex.

Exceptions
System.ArgumentOutOfRangeException

Argument must be one of the following values: 2, 4, or 8.

See Also

ShadingType

Gets the FreeTriangleMesh value.

public override PdfShadingType ShadingType { get; }
Public Overrides ReadOnly Property ShadingType As PdfShadingType
Property Value
PdfShadingType

The FreeTriangleMesh value.

Overrides

Methods

Add(PdfMeshSharedEdge, PdfMeshVertex)

Populates a mesh with a subsequent, connected, triangle.

If the edgeFlag is Edge1, then the edge between the second (Vertex1) and the third (Vertex2) vertex of the previous triangle is shared with a subsequent, connected, triangle as an edge between its first (Vertex0) and second (Vertex1) vertex.

If the edgeFlag is Edge2, then the edge between the first (Vertex0) and the third (Vertex2) vertex of the previous triangle is shared with a subsequent, connected, triangle as an edge between its first (Vertex0) and second (Vertex1) vertex.

public void Add(PdfMeshSharedEdge edgeFlag, PdfMeshVertex vertex2)
Public Sub Add(edgeFlag As PdfMeshSharedEdge, vertex2 As PdfMeshVertex)
Parameters
edgeFlag
PdfMeshSharedEdge

The flag specifying the edge of the previous triangle that is shared with a subsequent, connected, triangle.

vertex2
PdfMeshVertex

The third vertex of a subsequent, connected, triangle.

Exceptions
System.ArgumentOutOfRangeException

The edgeFlag must be Edge1 or Edge2.

System.ArgumentException

The Function entry is set and the IsColorParametric property of vertex2 is false or the Function entry is not set and the IsColorParametric property of vertex2 is true.

System.ArgumentException

The Space of the Color of vertex2 is not equal to the shading's ColorSpace.

System.InvalidOperationException

This overload cannot be used on an empty mesh. Use the Add(PdfMeshVertex, PdfMeshVertex, PdfMeshVertex) overload before.

Add(PdfMeshVertex, PdfMeshVertex, PdfMeshVertex)

Populates a mesh with a new triangle, unconnected to any other.

public void Add(PdfMeshVertex vertex0, PdfMeshVertex vertex1, PdfMeshVertex vertex2)
Public Sub Add(vertex0 As PdfMeshVertex, vertex1 As PdfMeshVertex, vertex2 As PdfMeshVertex)
Parameters
vertex0
PdfMeshVertex

The first vertex of a new triangle.

vertex1
PdfMeshVertex

The second vertex of a new triangle.

vertex2
PdfMeshVertex

The third vertex of a new triangle.

Exceptions
System.ArgumentException

The Function entry is set and the IsColorParametric property of vertex0, vertex1, or vertex2 is false or the Function entry is not set and the IsColorParametric property of vertex0, vertex1, or vertex2 is true.

System.ArgumentException

The Space of the Color of vertex0, vertex1, or vertex2 is not equal to the shading's ColorSpace.

GetEnumerator()

Returns an enumerator that iterates PdfMeshTriangles contained in this PdfFreeTriangleMeshShading.

public PdfFreeTriangleMeshShading.Enumerator GetEnumerator()
Public Function GetEnumerator As PdfFreeTriangleMeshShading.Enumerator
Returns
PdfFreeTriangleMeshShading.Enumerator
Exceptions
System.InvalidOperationException

Pack(Boolean)

Packs the mesh data to the underlying PdfStream and, optionally, sets or adjusts the mesh data serialization settings (BitsPerCoordinate, BitsPerComponent, BitsPerFlag, and Decode entries) to the most appropriate values to achieve the best sampled mesh data compaction and resolution, based on the mesh data.

public PdfFreeTriangleMeshShading Pack(bool resolveSerializationSettings = true)
Public Function Pack(resolveSerializationSettings As Boolean = True) As PdfFreeTriangleMeshShading
Parameters
resolveSerializationSettings
System.Boolean

true to set or adjust the mesh data serialization settings (BitsPerCoordinate, BitsPerComponent, BitsPerFlag, and Decode entries) to the most appropriate values to achieve the best sampled mesh data compaction and resolution, based on the mesh data; otherwise, false.

Returns
PdfFreeTriangleMeshShading

A reference to this PdfFreeTriangleMeshShading instance after the packing operation has completed.

Exceptions
System.InvalidOperationException

Some of the PdfNumberRanges in the Decode entry are too narrow to encode the mesh data. Extend the bounds of those PdfNumberRanges or use the Pack(Boolean) method with a parameter resolveSerializationSettings set to true.

Inherited Properties

Background

(Optional) A color appropriate to the ColorSpace, specifying a single background color. If present, this color shall be used, before any painting operation involving the shading, to fill those portions of the area to be painted that lie outside the bounds of the shading object.

note

In the opaque imaging model, the effect is as if the painting operation were performed twice: first with the background color and then with the shading.

note

The background color is applied only when the shading is used as part of a PdfShadingPattern, not when it is painted directly with the PdfShadingContent operator.

(Inherited from PdfShading)

BitsPerComponent

(Required) The number of bits used to represent each color component. The value shall be 1, 2, 4, 8, 12, or 16.

(Inherited from PdfMeshShading)

BitsPerCoordinate

(Required) The number of bits used to represent each vertex or geometric coordinate. The value shall be 1, 2, 4, 8, 12, 16, 24, or 32.

(Inherited from PdfMeshShading)

BoundingBox

(Optional) A rectangle giving the left, bottom, right, and top coordinates, respectively, of the shading's bounding box. The coordinates shall be interpreted in the shading's target coordinate space. If present, this bounding box shall be applied as a temporary clipping boundary when the shading is painted, in addition to the current clipping path and any other clipping boundaries in effect at that time.

(Inherited from PdfShading)

ColorSpace

(Required) The color space in which color values shall be expressed. This may be any device, CIE-based, or special color space except a Pattern space. See 8.7.4.4, "Color Space: Special Considerations" for further information.

(Inherited from PdfShading)

Decode

(Required) A collection of PdfNumberRanges specifying how to map vertex or geometric coordinates and color components into the appropriate ranges of values. The decoding method is similar to that used in image dictionaries (see 8.9.5.2, "Decode Arrays"). The ranges shall be specified as follows:

[(xmin xmax) (ymin ymax) (c1,min c1,max) … (cn,min cn,max)]

Only one pair of c values shall be specified if a Function entry is present.

(Inherited from PdfMeshShading)

Document

Gets the PdfDocument associated with this PdfContentResource or null if no PdfDocument is associated with this PdfContentResource.

(Inherited from PdfContentResource)

Function

(Optional) A 1-in, n-out function or an array of n 1-in, 1-out functions (where n is the number of color components in the shading dictionary's color space). If this entry is present, the color data for each vertex shall be specified by a single parametric variable rather than by n separate color components. The designated function(s) shall be called with each interpolated value of the parametric variable to determine the actual color at each point. Each input value shall be forced into the range interval specified for the corresponding color component in the shading dictionary's Decode array. Each function's domain shall be a superset of that interval. If the value returned by the function for a given color component is out of range, it shall be adjusted to the nearest valid value.

This entry shall not be used with an Indexed color space.

tip

Use the static method CreateFunction(IList<PdfShadingColor>) to create an interpolation function from two or more PdfShadingColors.

(Inherited from PdfMeshShading)

IsAntiAlias

(Optional) A flag indicating whether to filter the shading function to prevent aliasing artifacts.

note

The shading operators sample shading functions at a rate determined by the resolution of the output device. Aliasing can occur if the function is not smooth—that is, if it has a high spatial frequency relative to the sampling rate. Anti-aliasing can be computationally expensive and is usually unnecessary, since most shading functions are smooth enough or are sampled at a high enough frequency to avoid aliasing effects. Anti-aliasing may not be implemented on some output devices, in which case this flag is ignored.

Default value: false.

(Inherited from PdfShading)

Metadata

(Optional; PDF 1.4) A metadata stream containing metadata for the component.

(Inherited from PdfObject)

Inherited Methods

CreateFunction(System.Collections.Generic.IList<PdfShadingColor>)

Creates an interpolation function from the specified list of PdfShadingColors.

Two colors create a PdfExponentialInterpolationFunction and more than two create a PdfStitchingFunction (stitching two or more PdfExponentialInterpolationFunctions).

The function's Domain is set from the Offset of the first and the last PdfShadingColor.

(Inherited from PdfShading)

SetBoundingBox(System.Double, System.Double, System.Double, System.Double)

Sets the BoundingBox.

(Inherited from PdfShading)

Implements

System.Collections.Generic.IEnumerable<T>
System.Collections.IEnumerable

Extension Methods

See Also