PdfFunctionBasedShading Class

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

In Type 1 (function-based) shadings, the color at every point in the domain is defined by a specified mathematical function. The function need not be smooth or continuous. This type is the most general of the available shading types and is useful for shadings that cannot be adequately described with any of the other types.

public sealed class PdfFunctionBasedShading : PdfShading
Public NotInheritable Class PdfFunctionBasedShading
    Inherits PdfShading
Inheritance:
System.Object
PdfFunctionBasedShading

Constructors

PdfFunctionBasedShading(PdfFunction, PdfColorSpace)

Initializes a new instance of the PdfFunctionBasedShading class.

The DomainX and DomainY are set from the function's Domain.

Use the SetTransform(PdfPoint, PdfSize) method afterwards if DomainX and DomainY do not correspond to the shading's target coordinate space.

public PdfFunctionBasedShading(PdfFunction function, PdfColorSpace colorSpace = null)
Public Sub New(function As PdfFunction, colorSpace As PdfColorSpace = Nothing)
Parameters
function
PdfFunction

A 2-in, n-out function (where n is the number of color components in the shading dictionary's color space).

colorSpace
PdfColorSpace

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

Exceptions
System.ArgumentNullException

function is null.

System.ArgumentException

The function's input dimensionality is invalid (the Domain's Count should be 2) or the function's output dimensionality is invalid (should be equal to the ColorSpace.ColorantCount).

System.InvalidOperationException

Interpolation via the Function entry is invalid in an Indexed color space, which is quantized and therefore inappropriate for calculations that assume a continuous range of colors.

PdfFunctionBasedShading(IList<PdfFunction>, PdfColorSpace)

Initializes a new instance of the PdfFunctionBasedShading class.

The DomainX and DomainY are set as a subset of the Domain of all PdfFunctions contained in the function list.

Use the SetTransform(PdfPoint, PdfSize) method afterwards if DomainX and DomainY do not correspond to the shading's target coordinate space.

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

An array of n 2-in, 1-out functions (where n is the number of color components in the shading dictionary's color space).

colorSpace
PdfColorSpace

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

Exceptions
System.ArgumentNullException

function is null or empty or any of its elements is null.

System.ArgumentException

The function's count is not equal to the ColorSpace.ColorantCount or the function's input dimensionality is invalid (the Domain's Count should be 2) or the function's output dimensionality is invalid (should be 1) for any PdfFunction contained in the function list.

System.InvalidOperationException

Interpolation via the Function entry is invalid in an Indexed color space, which is quantized and therefore inappropriate for calculations that assume a continuous range of colors.

Properties

DomainX

A PdfNumberRange specifying the horizontal component of the rectangular domain of coordinates over which the color function(s) are defined.

Default value: [0, 1].

public PdfNumberRange DomainX { get; set; }
Public Property DomainX As PdfNumberRange
Property Value
PdfNumberRange

A PdfNumberRange specifying the horizontal component of the rectangular domain of coordinates over which the color function(s) are defined.

See Also

DomainY

A PdfNumberRange specifying the vertical component of the rectangular domain of coordinates over which the color function(s) are defined.

Default value: [0, 1].

public PdfNumberRange DomainY { get; set; }
Public Property DomainY As PdfNumberRange
Property Value
PdfNumberRange

A PdfNumberRange specifying the vertical component of the rectangular domain of coordinates over which the color function(s) are defined.

See Also

Function

(Required) A 2-in, n-out function or an array of n 2-in, 1-out functions (where n is the number of color components in the shading dictionary's color space). Each function's domain shall be a superset of that of the shading dictionary. 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.

public IList<PdfFunction> Function { get; set; }
Public Property Function As IList(Of PdfFunction)
Property Value
System.Collections.Generic.IList<PdfFunction>

A 2-in, n-out function or an array of n 2-in, 1-out functions.

Exceptions
System.ArgumentNullException

Value is null or empty or any of its elements is null.

System.ArgumentException

The number of functions is not 1 and is not equal to the ColorSpace.ColorantCount or the function's input dimensionality is invalid (the Domain's Count should be 2) or the function's output dimensionality is invalid (if the number of functions is 1, then it should be equal to the ColorSpace.ColorantCount; otherwise, it should be 1) for any function contained in the PdfFunction list.

System.InvalidOperationException

Interpolation via the Function entry is invalid in an Indexed color space, which is quantized and therefore inappropriate for calculations that assume a continuous range of colors.

See Also

ShadingType

Gets the FunctionBased value.

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

The FunctionBased value.

Overrides

Transform

(Optional) An array of six numbers specifying a transformation matrix mapping the coordinate space specified by DomainX and DomainY entries into the shading's target coordinate space.

note

To map the domain rectangle [{0, 1}, {0, 1}] to a 1-inch square with lower-left corner at coordinates (100, 100) in default user space, the Transform value would be [72 0 0 72 100 100].

Default value: the Identity matrix [1 0 0 1 0 0].

public PdfMatrix Transform { get; set; }
Public Property Transform As PdfMatrix
Property Value
PdfMatrix

An array of six numbers specifying a transformation matrix mapping the coordinate space specified by DomainX and DomainY entries into the shading's target coordinate space.

See Also

Methods

SetTransform(PdfPoint, PdfSize)

Sets the Transform to a a PdfMatrix that transforms the rectangle specified by DomainX and DomainY entries to the rectangle specified by point and size parameters. This method is useful if the shading's DomainX and DomainY doesn't correspond to the shading's target coordinate space.

public PdfFunctionBasedShading SetTransform(PdfPoint point, PdfSize size)
Public Function SetTransform(point As PdfPoint, size As PdfSize) As PdfFunctionBasedShading
Parameters
point
PdfPoint

The point in the shading's target coordinate space to which the point (DomainX.First, DomainY.First) is mapped to.

size
PdfSize

The area in the shading's target coordinate space to which the area [DomainX.Last - DomainX.First, DomainY.Last - DomainY.First] is mapped to.

Returns
PdfFunctionBasedShading

A reference to this PdfFunctionBasedShading instance after the setting the Transform has completed.

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)

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)

Document

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

(Inherited from PdfContentResource)

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)

Extension Methods

See Also