Clips are used to define complex clipping regions for vectors.
The VectorClip defines a clipping path that can be used by other vectors as a mask. The clipping path is defined by creating Vector shapes that are initialised to the VectorClip's Viewport as child objects.
Vector shapes can utilise a VectorClip by referring to it via the Vector's Vector⇒Mask field.
VectorClip objects must be owned by a VectorScene. It is valid for a VectorClip to be shared amongst multiple vector objects within the same scene. If optimum drawing efficiency is required, we recommend that each VectorClip is referenced by one vector only. This will reduce the frequency of path recomputation and redrawing of the clipping path.
The SVG standard makes a distinction between clipping paths and masks. Consequently, this distinction also exists in the VectorClip design, and by default VectorClip objects will operate in path clipping mode. This means that the clipping path is constructed as a solid filled area, and stroke instructions are completely ignored. To create more complex masks, such as one with a filled gradient, use the VCLF::APPLY_FILLS option in Flags. If stroking operations are required, define VCLF::APPLY_STROKES.
Finally, for the purposes of UI development it may often be beneficial to set Units to VUNIT::BOUNDING_BOX so that the clipping path is sized to match the target vector. A viewbox size of 0 0 1 1 is applied by default, but if a 1:1 match to the target vector is preferred, set the Viewport VectorViewport⇒ViewWidth and VectorViewport⇒ViewHeight to match the target vector's dimensions.
The VectorClip class consists of the following fields:
Access | Name | Type | Comment | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Flags | VCLF | Optional flags. | |||||||||
| |||||||||||
| Units | VUNIT | Defines the coordinate system for fields X, Y, Width and Height. | |||||||||
The default coordinate system for clip-paths is
| |||||||||||
| Viewport | *VectorViewport | This viewport hosts the Vector objects that will contribute to the clip path. | |||||||||
To define the path(s) that will be used to build the clipping mask, add at least one Vector object to the viewport declared here. | |||||||||||