PdfRadialShading Class

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

Type 3 (radial) shadings define a color blend that varies between two circles. Shadings of this type are commonly used to depict three-dimensional spheres and cones.

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

Constructors

PdfRadialShading(PdfPoint, Double, PdfPoint, Double, PdfColorSpace)

Initializes a new instance of the PdfRadialShading class that has the specified StartCenter, StartRadius, EndCenter, EndRadius and, optionally, ColorSpace. The Function property should be set subsequently.

public PdfRadialShading(PdfPoint startCenter, double startRadius, PdfPoint endCenter, double endRadius, PdfColorSpace colorSpace = null)
Public Sub New(startCenter As PdfPoint, startRadius As Double, endCenter As PdfPoint, endRadius As Double, colorSpace As PdfColorSpace = Nothing)
Parameters
startCenter
PdfPoint

The center of the starting circle, expressed in the shading's target coordinate space.

startRadius
System.Double

The radius of the starting circle, expressed in the shading's target coordinate space. The radius shall be greater than or equal to 0. If radius is 0, the circle shall be treated as a point; if both startRadius and endRadius are 0, nothing shall be painted.

endCenter
PdfPoint

The center of the ending circle, expressed in the shading's target coordinate space.

endRadius
System.Double

The radius of the ending circle, expressed in the shading's target coordinate space. The radius shall be greater than or equal to 0. If radius is 0, the circle shall be treated as a point; if both startRadius and endRadius are 0, nothing shall be painted.

colorSpace
PdfColorSpace

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

Exceptions
System.ArgumentOutOfRangeException

startRadius or endRadius is negative.

PdfRadialShading(PdfPoint, Double, PdfPoint, Double, PdfShadingColor[])

Initializes a new instance of the PdfRadialShading class that has the specified StartCenter, StartRadius, EndCenter, EndRadius and shading colors.

Two colors are converted to a PdfExponentialInterpolationFunction and more than two are converted to a PdfStitchingFunction (stitching two or more PdfExponentialInterpolationFunctions) that is then set to the Function.

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

public PdfRadialShading(PdfPoint startCenter, double startRadius, PdfPoint endCenter, double endRadius, params PdfShadingColor[] colors)
Public Sub New(startCenter As PdfPoint, startRadius As Double, endCenter As PdfPoint, endRadius As Double, ParamArray colors As PdfShadingColor())
Parameters
startCenter
PdfPoint

The center of the starting circle, expressed in the shading's target coordinate space.

startRadius
System.Double

The radius of the starting circle, expressed in the shading's target coordinate space. The radius shall be greater than or equal to 0. If radius is 0, the circle shall be treated as a point; if both startRadius and endRadius are 0, nothing shall be painted.

endCenter
PdfPoint

The center of the ending circle, expressed in the shading's target coordinate space.

endRadius
System.Double

The radius of the ending circle, expressed in the shading's target coordinate space. The radius shall be greater than or equal to 0. If radius is 0, the circle shall be treated as a point; if both startRadius and endRadius are 0, nothing shall be painted.

colors
PdfShadingColor[]

The PdfShadingColors to set on this shading.

Exceptions
System.ArgumentOutOfRangeException

startRadius or endRadius is negative.

System.ArgumentNullException

colors is null.

System.ArgumentException

colors count is less than 2 or Color space of any PdfShadingColor is not equal to the ColorSpace or Offset of any PdfShadingColor is not greater than the Offset of all previous PdfShadingColors.

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.

PdfRadialShading(PdfPoint, Double, PdfPoint, Double, PdfColor, PdfColor)

Initializes a new instance of the PdfRadialShading class that has the specified StartCenter, StartRadius, EndCenter, EndRadius and two shading colors.

Colors startColor and endColor are converted to a PdfExponentialInterpolationFunction that is then set to the Function.

public PdfRadialShading(PdfPoint startCenter, double startRadius, PdfPoint endCenter, double endRadius, PdfColor startColor, PdfColor endColor)
Public Sub New(startCenter As PdfPoint, startRadius As Double, endCenter As PdfPoint, endRadius As Double, startColor As PdfColor, endColor As PdfColor)
Parameters
startCenter
PdfPoint

The center of the starting circle, expressed in the shading's target coordinate space.

startRadius
System.Double

The radius of the starting circle, expressed in the shading's target coordinate space. The radius shall be greater than or equal to 0. If radius is 0, the circle shall be treated as a point; if both startRadius and endRadius are 0, nothing shall be painted.

endCenter
PdfPoint

The center of the ending circle, expressed in the shading's target coordinate space.

endRadius
System.Double

The radius of the ending circle, expressed in the shading's target coordinate space. The radius shall be greater than or equal to 0. If radius is 0, the circle shall be treated as a point; if both startRadius and endRadius are 0, nothing shall be painted.

startColor
PdfColor

The shading color at the center of the starting circle.

endColor
PdfColor

The shading color at the center of the ending circle.

Exceptions
System.ArgumentOutOfRangeException

startRadius or endRadius is negative.

System.ArgumentException

Color Space of startColor and endColor are not equal.

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.

PdfRadialShading(PdfPoint, Double, PdfPoint, Double, IList<PdfShadingColor>)

Initializes a new instance of the PdfRadialShading class that has the specified StartCenter, StartRadius, EndCenter, EndRadius and shading colors.

Two colors are converted to a PdfExponentialInterpolationFunction and more than two are converted to a PdfStitchingFunction (stitching two or more PdfExponentialInterpolationFunctions) that is then set to the Function.

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

public PdfRadialShading(PdfPoint startCenter, double startRadius, PdfPoint endCenter, double endRadius, IList<PdfShadingColor> colors)
Public Sub New(startCenter As PdfPoint, startRadius As Double, endCenter As PdfPoint, endRadius As Double, colors As IList(Of PdfShadingColor))
Parameters
startCenter
PdfPoint

The center of the starting circle, expressed in the shading's target coordinate space.

startRadius
System.Double

The radius of the starting circle, expressed in the shading's target coordinate space. The radius shall be greater than or equal to 0. If radius is 0, the circle shall be treated as a point; if both startRadius and endRadius are 0, nothing shall be painted.

endCenter
PdfPoint

The center of the ending circle, expressed in the shading's target coordinate space.

endRadius
System.Double

The radius of the ending circle, expressed in the shading's target coordinate space. The radius shall be greater than or equal to 0. If radius is 0, the circle shall be treated as a point; if both startRadius and endRadius are 0, nothing shall be painted.

colors
System.Collections.Generic.IList<PdfShadingColor>

The PdfShadingColors to set on this shading.

Exceptions
System.ArgumentOutOfRangeException

startRadius or endRadius is negative.

System.ArgumentNullException

colors is null.

System.ArgumentException

colors count is less than 2 or Color space of any PdfShadingColor is not equal to the ColorSpace or Offset of any PdfShadingColor is not greater than the Offset of all previous PdfShadingColors.

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

Domain

(Optional) A PdfNumberRange specifying the limiting values of a parametric variable t. The variable is considered to vary linearly between these two values as the color gradient varies between the starting and ending circles. The variable t becomes the input argument to the color function(s).

Default value: [0, 1].

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

A PdfNumberRange specifying the limiting values of a parametric variable t.

See Also

EndCenter

(Required) The center of the ending circle, expressed in the shading's target coordinate space.

public PdfPoint EndCenter { get; set; }
Public Property EndCenter As PdfPoint
Property Value
PdfPoint

The center of the ending circle, expressed in the shading's target coordinate space.

See Also

EndRadius

(Required) The radius of the ending circle, expressed in the shading's target coordinate space. The radius shall be greater than or equal to 0. If radius is 0, the circle shall be treated as a point; if both StartRadius and EndRadius are 0, nothing shall be painted.

public double EndRadius { get; set; }
Public Property EndRadius As Double
Property Value
System.Double

The radius of the ending circle, expressed in the shading's target coordinate space.

Exceptions
System.ArgumentOutOfRangeException

The StartRadius property value must be greater than or equal to zero.

See Also

ExtendEndCircle

(Optional) A boolean value specifying whether to extend the shading beyond the ending circle.

Default value: false.

public bool ExtendEndCircle { get; set; }
Public Property ExtendEndCircle As Boolean
Property Value
System.Boolean

A boolean value specifying whether to extend the shading beyond the ending circle.

See Also

ExtendStartCircle

(Optional) A boolean value specifying whether to extend the shading beyond the starting circle.

Default value: false.

public bool ExtendStartCircle { get; set; }
Public Property ExtendStartCircle As Boolean
Property Value
System.Boolean

A boolean value specifying whether to extend the shading beyond the starting circle.

See Also

Function

(Required) 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). The function(s) shall be called with values of the parametric variable t in the domain defined by the Domain entry. 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.

tip

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

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

A 1-in, n-out function or an array of n 1-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 1) 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 Radial value.

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

The Radial value.

Overrides

StartCenter

(Required) The center of the starting circle, expressed in the shading's target coordinate space.

public PdfPoint StartCenter { get; set; }
Public Property StartCenter As PdfPoint
Property Value
PdfPoint

The center of the starting circle, expressed in the shading's target coordinate space.

See Also

StartRadius

(Required) The radius of the starting circle, expressed in the shading's target coordinate space. The radius shall be greater than or equal to 0. If radius is 0, the circle shall be treated as a point; if both StartRadius and EndRadius are 0, nothing shall be painted.

public double StartRadius { get; set; }
Public Property StartRadius As Double
Property Value
System.Double

The radius of the starting circle, expressed in the shading's target coordinate space.

Exceptions
System.ArgumentOutOfRangeException

The StartRadius property value must be greater than or equal to zero.

See Also

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