CeresEngine 0.2.0
A game development framework
Loading...
Searching...
No Matches
CeresEngine::Shape Class Reference

A type that describes a conjunction of shapes that can be filled and stroked. More...

#include <CeresEngine/Graphics/Shape.hpp>

Classes

struct  Element
 An element is composed of a path and one or more commands to be done on that path. More...
 

Public Types

enum class  LineCapStyle { Butt , Round , Square }
 Constants that specify the shape of endpoints for an open path when it is stroked. More...
 
enum class  LineJoinStyle { Miter , Round , Bevel }
 Constants that specify the shape of the joins between connected segments of a stroked path. More...
 
enum class  BlendMode {
  Normal , Multiply , Screen , Overlay ,
  Darken , Lighten , ColorDodge , ColorBurn ,
  SoftLight , HardLight , Difference , Exclusion ,
  Hue , Saturation , Color , Luminosity ,
  Clear , Copy , SourceIn , SourceOut ,
  SourceAtop , DestinationOver , DestinationIn , DestinationOut ,
  DestinationAtop , XorOp , PlusDarker , PlusLighter
}
 Compositing operations for images. More...
 
enum class  ElementType { Fill , Stroke }
 
using ElementIterator = typename Deque< Element >::const_iterator
 An iterator type that allows iterating over the shape elements.
 
using allocator_type = AnyStdAllocator< Shape >
 

Public Member Functions

 Shape ()
 Creates a new empty shape using a default allocator.
 
 Shape (AnyAllocatorReference allocator)
 Creates a new empty shape using a custom allocator.
 
 Shape (const Shape &other)
 
Shapeoperator= (const Shape &other)
 
 Shape (const Shape &other, AnyAllocatorReference allocator)
 
 Shape (Shape &&other) noexcept
 
Shapeoperator= (Shape &&other) noexcept
 
 ~Shape ()=default
 
template<typename Allocator >
 Shape (std::allocator_arg_t, const Allocator &allocator)
 Creates a new empty shape using a custom allocator.
 
template<typename Allocator >
 Shape (std::allocator_arg_t, const Allocator &allocator, const Shape &other)
 
void stroke (const BezierPath &path, const Paint &paint, double lineWidth=1.0, BlendMode blendMode=BlendMode::Normal, LineCapStyle lineCapStyle=LineCapStyle::Butt, LineJoinStyle lineJoinStyle=LineJoinStyle::Miter, double miterLimit=10.0)
 Draws a line along the path using the given stroke color and drawing attributes.
 
void stroke (BezierPath &&path, const Paint &paint, double lineWidth=1.0, BlendMode blendMode=BlendMode::Normal, LineCapStyle lineCapStyle=LineCapStyle::Butt, LineJoinStyle lineJoinStyle=LineJoinStyle::Miter, double miterLimit=10.0)
 Draws a line along the path using the given stroke color and drawing attributes.
 
void fill (const BezierPath &path, const Paint &paint, BlendMode blendMode=BlendMode::Normal)
 Paints the region enclosed by the path.
 
void fill (BezierPath &&path, const Paint &paint, BlendMode blendMode=BlendMode::Normal)
 Paints the region enclosed by the path.
 
void append (const Shape &aShape)
 Appends the contents of the specified shape object to the shape.
 
void append (Shape &&aShape)
 Appends the contents of the specified shape object to the shape.
 
Shapeoperator+= (const Shape &aShape)
 Appends the contents of the specified shape object to the shape.
 
Shapeoperator+= (Shape &&aShape)
 Appends the contents of the specified shape object to the shape.
 
Shape operator+ (const Shape &aShape) const
 Appends the contents of the specified shape object to the shape.
 
Shape operator+ (Shape &&aShape) const
 Appends the contents of the specified shape object to the shape.
 
void transform (const AffineTransform &aTransform)
 Transforms all points in the shape using the specified transform.
 
Shape transformed (const AffineTransform &aTransform) const &
 Transforms all points in the shape using the specified transform.
 
Shape && transformed (const AffineTransform &aTransform) &&
 Transforms all points in the shape using the specified transform.
 
bool contains (const Point2 &aPoint) const
 Returns a Boolean value that indicates whether the shape contains the specified point.
 
bool operator& (const Point2 &aPoint) const
 Returns a Boolean value that indicates whether the shape contains the specified point.
 
void flatten ()
 Computes a flattened version of the shape object.
 
Shape flattened () const &
 Computes a flattened version of the shape object.
 
Shape && flattened () &&
 Computes a flattened version of the shape object.
 
void reverse ()
 Computes a shape containing the reversed contents of the current shape path objects.
 
Shape reversed () const &
 Computes a shape containing the reversed contents of the current shape path objects.
 
Shape && reversed () &&
 Computes a shape containing the reversed contents of the current shape path objects.
 
Rect2 getBounds () const
 The bounding box of the shape.
 
Rect2 getControlPointBounds () const
 The bounding box of the shape, including any control points.
 
Rect2 getBoundsAccurate () const
 The bounding box of the shape.
 
bool isEmpty () const
 A Boolean value that indicates whether the shape is empty.
 
UInt32 getElementCount () const
 The total number of shape elements in the shape.
 
const ElementgetElement (UInt32 index) const
 Returns the type of shape element at the specified index.
 
const Elementoperator[] (const UInt32 index) const
 Returns the type of shape element at the specified index.
 
ElementIterator cbegin () const
 Returns an iterator that points to the first path element.
 
ElementIterator begin () const
 Returns an iterator that points to the first path element.
 
ElementIterator cend () const
 Returns an iterator that points to past-the-last path element.
 
ElementIterator end () const
 Returns an iterator that points to past-the-last path element.
 
AnyAllocatorReference getAllocator () const noexcept
 

Private Member Functions

const BezierPathappendPath (const BezierPath &path)
 Appends a path to the internal list of paths.
 
const BezierPathappendPath (BezierPath &&path)
 Appends a path to the internal list of paths.
 
ElementappendElement (ElementType type, const BezierPath &path)
 Appends a new element to the shape.
 
ElementappendElement (ElementType type, BezierPath &&path)
 Appends a new element to the shape.
 

Private Attributes

Deque< BezierPath, AnyAllocatormPaths {gDefaultAllocator()}
 A vector that stores a unique copy of each path.
 
Deque< Element, AnyAllocatormElements {gDefaultAllocator()}
 A vector of all elements in the shape.
 

Detailed Description

A type that describes a conjunction of shapes that can be filled and stroked.

For a given Shape object, you can stroke the path's outline or fill the region occupied by a BezierPath. Using methods of Shape, you can also perform hit detection on the filled or stroked path. Hit detection is needed to implement interactive graphics, as in rubber banding and dragging operations.

Member Typedef Documentation

◆ allocator_type

◆ ElementIterator

An iterator type that allows iterating over the shape elements.

Member Enumeration Documentation

◆ BlendMode

Compositing operations for images.

These blend mode constants represent the Porter-Duff blend modes. The symbols in the equations for these blend modes are:

  • R is the premultiplied result
  • S is the source color, and includes alpha
  • D is the destination color, and includes alpha
  • Ra, Sa, and Da are the alpha components of R, S, and D

You can find more information on blend modes, including examples of images produced using them, and many mathematical descriptions of the modes, in PDF Reference, Fourth Edition, Version 1.5, Adobe Systems, Inc. If you are a former QuickDraw developer, it may be helpful for you to think of blend modes as an alternative to transfer modes.

Enumerator
Normal 

Paints the source image samples over the background image samples.

Multiply 

Multiplies the source image samples with the background image samples.

This results in colors that are at least as dark as either of the two contributing sample colors.

Screen 

Multiplies the inverse of the source image samples with the inverse of the background image samples, resulting in colors that are at least as light as either of the two contributing sample colors.

Overlay 

TODO.

Darken 

TODO.

Lighten 

TODO.

ColorDodge 

Brightens the background image samples to reflect the source image samples.

Source image sample values that specify black do not produce a change.

ColorBurn 

Darkens the background image samples to reflect the source image samples.

Source image sample values that specify white do not produce a change.

SoftLight 

TODO.

HardLight 

TODO.

Difference 

TODO.

Exclusion 

Produces an effect similar to that produced by difference, but with lower contrast.

Source image sample values that are black don’t produce a change; white inverts the background color values.

Hue 

Uses the luminance and saturation values of the background with the hue of the source image.

Saturation 

Uses the luminance and hue values of the background with the saturation of the source image.

Areas of the background that have no saturation (that is, pure gray areas) don’t produce a change.

Color 

Uses the luminance values of the background with the hue and saturation values of the source image.

This mode preserves the gray levels in the image. You can use this mode to color monochrome images or to tint color images.

Luminosity 

Uses the hue and saturation of the background with the luminance of the source image.

This mode creates an effect that is inverse to the effect created by color.

Clear 

R = 0.

Copy 

R = S.

SourceIn 

R = S*Da.

SourceOut 

R = S*(1 - Da)

SourceAtop 

R = S*Da + D*(1 - Sa)

DestinationOver 

R = S*(1 - Da) + D.

DestinationIn 

R = D*Sa.

DestinationOut 

R = D*(1 - Sa)

DestinationAtop 

R = S*(1 - Da) + D*Sa.

XorOp 

R = S*(1 - Da) + D*(1 - Sa).

This XOR mode is only nominally related to the classical bitmap XOR operation, which is not supported by the framework.

PlusDarker 

R = MAX(0, 1 - ((1 - D) + (1 - S)))

PlusLighter 

R = MIN(1, S + D)

◆ ElementType

Enumerator
Fill 
Stroke 

◆ LineCapStyle

Constants that specify the shape of endpoints for an open path when it is stroked.

Enumerator
Butt 

Specifies a butt line cap style for endpoints for an open path when stroked.

Round 

Specifies a round line cap style for endpoints for an open path when stroked.

Square 

Specifies a square line cap style for endpoints for an open path when stroked.

◆ LineJoinStyle

Constants that specify the shape of the joins between connected segments of a stroked path.

Enumerator
Miter 

Specifies a miter line shape of the joints between connected segments of a stroked path.

Round 

Specifies a round line shape of the joints between connected segments of a stroked path.

Bevel 

Specifies a bevel line shape of the joints between connected segments of a stroked path.

Constructor & Destructor Documentation

◆ Shape() [1/7]

CeresEngine::Shape::Shape ( )
explicit

Creates a new empty shape using a default allocator.

◆ Shape() [2/7]

CeresEngine::Shape::Shape ( AnyAllocatorReference  allocator)
explicit

Creates a new empty shape using a custom allocator.

Parameters
allocatorThe allocator to be used for memory allocations.

◆ Shape() [3/7]

CeresEngine::Shape::Shape ( const Shape other)

◆ Shape() [4/7]

CeresEngine::Shape::Shape ( const Shape other,
AnyAllocatorReference  allocator 
)

◆ Shape() [5/7]

CeresEngine::Shape::Shape ( Shape &&  other)
noexcept

◆ ~Shape()

CeresEngine::Shape::~Shape ( )
default

◆ Shape() [6/7]

template<typename Allocator >
CeresEngine::Shape::Shape ( std::allocator_arg_t  ,
const Allocator &  allocator 
)
inlineexplicit

Creates a new empty shape using a custom allocator.

Parameters
allocatorThe allocator to be used for memory allocations.

◆ Shape() [7/7]

template<typename Allocator >
CeresEngine::Shape::Shape ( std::allocator_arg_t  ,
const Allocator &  allocator,
const Shape other 
)
inlineexplicit

Member Function Documentation

◆ append() [1/2]

void CeresEngine::Shape::append ( const Shape aShape)

Appends the contents of the specified shape object to the shape.

This method adds the commands used to create aShape to the end of the receiver's shape.

Parameters
aShapeThe shape to add to the receiver.

◆ append() [2/2]

void CeresEngine::Shape::append ( Shape &&  aShape)

Appends the contents of the specified shape object to the shape.

This method adds the commands used to create aShape to the end of the receiver's shape.

Parameters
aShapeThe shape to add to the receiver.

◆ appendElement() [1/2]

Element & CeresEngine::Shape::appendElement ( ElementType  type,
BezierPath &&  path 
)
private

Appends a new element to the shape.

The path will be appended to the internal path list if needed.

Parameters
typeThe shape element type.
pathThe shape bezier path. If needed, will be appended into the internal list.
Returns
A reference to the newly appended shape element.

◆ appendElement() [2/2]

Element & CeresEngine::Shape::appendElement ( ElementType  type,
const BezierPath path 
)
private

Appends a new element to the shape.

The path will be appended to the internal path list if needed.

Parameters
typeThe shape element type.
pathThe shape bezier path. If needed, will be appended into the internal list.
Returns
A reference to the newly appended shape element.

◆ appendPath() [1/2]

const BezierPath & CeresEngine::Shape::appendPath ( BezierPath &&  path)
private

Appends a path to the internal list of paths.

If an equal path already exists, it is returned instead.

Parameters
pathThe path to be appended.
Returns
A reference to stored path.

◆ appendPath() [2/2]

const BezierPath & CeresEngine::Shape::appendPath ( const BezierPath path)
private

Appends a path to the internal list of paths.

If an equal path already exists, it is returned instead.

Parameters
pathThe path to be appended.
Returns
A reference to stored path.

◆ begin()

ElementIterator CeresEngine::Shape::begin ( ) const
inline

Returns an iterator that points to the first path element.

◆ cbegin()

ElementIterator CeresEngine::Shape::cbegin ( ) const
inline

Returns an iterator that points to the first path element.

◆ cend()

ElementIterator CeresEngine::Shape::cend ( ) const
inline

Returns an iterator that points to past-the-last path element.

◆ contains()

bool CeresEngine::Shape::contains ( const Point2 &  aPoint) const

Returns a Boolean value that indicates whether the shape contains the specified point.

This method checks the point against the shape itself and the area it encloses. When determining hits in the enclosed area, this method uses the non-zero winding rule (nonZero). It does not take into account the line width used to stroke the path.

Parameters
aPointThe point to test against the shape, specified in the shape object's coordinate system.
Returns
true if the shape's enclosed area contains the specified point; otherwise, false.
See also
BezierPath::contains

◆ end()

ElementIterator CeresEngine::Shape::end ( ) const
inline

Returns an iterator that points to past-the-last path element.

◆ fill() [1/2]

void CeresEngine::Shape::fill ( BezierPath &&  path,
const Paint paint,
BlendMode  blendMode = BlendMode::Normal 
)

Paints the region enclosed by the path.

This method fills the path using the given fill color and the receiver's current winding rule. If the path contains any open subpaths, this method implicitly closes them before painting the fill region.

The painted region includes the pixels right up to, but not including, the path line itself. For paths with large line widths, this can result in overlap between the fill region and the stroked path (which is itself centered on the path line).

Parameters
pathThe path to be filled.
paintThe color to fill the path with.

◆ fill() [2/2]

void CeresEngine::Shape::fill ( const BezierPath path,
const Paint paint,
BlendMode  blendMode = BlendMode::Normal 
)

Paints the region enclosed by the path.

This method fills the path using the given fill color and the receiver's current winding rule. If the path contains any open subpaths, this method implicitly closes them before painting the fill region.

The painted region includes the pixels right up to, but not including, the path line itself. For paths with large line widths, this can result in overlap between the fill region and the stroked path (which is itself centered on the path line).

Parameters
pathThe path to be filled.
paintThe color to fill the path with.

◆ flatten()

void CeresEngine::Shape::flatten ( )

Computes a flattened version of the shape object.

Flattening a shape converts all it's paths segments into straight line approximations. The granularity of the approximations is controlled by the path's current flatness value, which is set using the BezierPath::setFlatness method.

See also
BezierPath::flattened

◆ flattened() [1/2]

Shape && CeresEngine::Shape::flattened ( ) &&
inline

Computes a flattened version of the shape object.

Flattening a shape converts all it's paths segments into straight line approximations. The granularity of the approximations is controlled by the path's current flatness value, which is set using the BezierPath::setFlatness method.

See also
BezierPath::flattened

◆ flattened() [2/2]

Shape CeresEngine::Shape::flattened ( ) const &

Computes a flattened version of the shape object.

Flattening a shape converts all it's paths segments into straight line approximations. The granularity of the approximations is controlled by the path's current flatness value, which is set using the BezierPath::setFlatness method.

See also
BezierPath::flattened

◆ getAllocator()

AnyAllocatorReference CeresEngine::Shape::getAllocator ( ) const
inlinenoexcept

◆ getBounds()

Rect2 CeresEngine::Shape::getBounds ( ) const

The bounding box of the shape.

This property contains the rectangle that encloses the shape of the receiver. If the shape contains curve segments, the bounding box encloses the curve but may not enclose the control points used to calculate the curve.

If the shape is empty, this method returns an empty rect.

See also
BezierPath::getBounds

◆ getBoundsAccurate()

Rect2 CeresEngine::Shape::getBoundsAccurate ( ) const

The bounding box of the shape.

This property contains the rectangle that encloses the shape of the receiver. This method performs a more accurate bounding box calculation by flattening the shape paths. This is a slow operation, so only use it when you actually need a precise bounding box.

If the shape is empty, this method returns an empty rect.

See also
BezierPath::getBoundsAccurate

◆ getControlPointBounds()

Rect2 CeresEngine::Shape::getControlPointBounds ( ) const

The bounding box of the shape, including any control points.

This property contains the rectangle that encloses the receiver's path. If the shape contains curve segments, the bounding box encloses the control points of the curves as well as the curves themselves.

See also
BezierPath::getControlPointBounds

◆ getElement()

const Element & CeresEngine::Shape::getElement ( UInt32  index) const

Returns the type of shape element at the specified index.

Path elements describe the commands used to draw a path and include basic commands such as filling and stroking. The elements are stored in the order of their execution.

Parameters
indexThe index of the desired shape element.
Returns
A reference to the internal Element structure.

◆ getElementCount()

UInt32 CeresEngine::Shape::getElementCount ( ) const

The total number of shape elements in the shape.

Each element type corresponds to one of the operations described in ElementType.

◆ isEmpty()

bool CeresEngine::Shape::isEmpty ( ) const

A Boolean value that indicates whether the shape is empty.

The value of this property is true if the shape contains no elements, or false if it contains at least one element.

◆ operator&()

bool CeresEngine::Shape::operator& ( const Point2 &  aPoint) const
inline

Returns a Boolean value that indicates whether the shape contains the specified point.

This method checks the point against the shape itself and the area it encloses. When determining hits in the enclosed area, this method uses the non-zero winding rule (nonZero). It does not take into account the line width used to stroke the path.

Parameters
aPointThe point to test against the shape, specified in the shape object's coordinate system.
Returns
true if the shape's enclosed area contains the specified point; otherwise, false.
See also
BezierPath::contains

◆ operator+() [1/2]

Shape CeresEngine::Shape::operator+ ( const Shape aShape) const
inline

Appends the contents of the specified shape object to the shape.

This method adds the commands used to create aShape to the end of the receiver's shape.

Parameters
aShapeThe shape to add to the receiver.

◆ operator+() [2/2]

Shape CeresEngine::Shape::operator+ ( Shape &&  aShape) const
inline

Appends the contents of the specified shape object to the shape.

This method adds the commands used to create aShape to the end of the receiver's shape.

Parameters
aShapeThe shape to add to the receiver.

◆ operator+=() [1/2]

Shape & CeresEngine::Shape::operator+= ( const Shape aShape)
inline

Appends the contents of the specified shape object to the shape.

This method adds the commands used to create aShape to the end of the receiver's shape.

Parameters
aShapeThe shape to add to the receiver.

◆ operator+=() [2/2]

Shape & CeresEngine::Shape::operator+= ( Shape &&  aShape)
inline

Appends the contents of the specified shape object to the shape.

This method adds the commands used to create aShape to the end of the receiver's shape.

Parameters
aShapeThe shape to add to the receiver.

◆ operator=() [1/2]

Shape & CeresEngine::Shape::operator= ( const Shape other)

◆ operator=() [2/2]

Shape & CeresEngine::Shape::operator= ( Shape &&  other)
noexcept

◆ operator[]()

const Element & CeresEngine::Shape::operator[] ( const UInt32  index) const
inline

Returns the type of shape element at the specified index.

Path elements describe the commands used to draw a path and include basic commands such as filling and stroking. The elements are stored in the order of their execution.

Parameters
indexThe index of the desired shape element.
Returns
A reference to the internal Element structure.

◆ reverse()

void CeresEngine::Shape::reverse ( )

Computes a shape containing the reversed contents of the current shape path objects.

The reversed shape does not necessarily have a different appearance when rendered. Instead, it changes the direction in which path segments are drawn. For example, reversing the path of a rectangle (whose line segments are normally drawn starting at the origin and proceeding in a counterclockwise direction) causes its line segments to be drawn in a clockwise direction instead. Drawing a reversed path could affect the appearance of a filled pattern, depending on the pattern and the fill rule in use.

The shape is created by reversing each whole or partial subpath in the path object individually.

See also
BezierPath::reversed

◆ reversed() [1/2]

Shape && CeresEngine::Shape::reversed ( ) &&
inline

Computes a shape containing the reversed contents of the current shape path objects.

The reversed shape does not necessarily have a different appearance when rendered. Instead, it changes the direction in which path segments are drawn. For example, reversing the path of a rectangle (whose line segments are normally drawn starting at the origin and proceeding in a counterclockwise direction) causes its line segments to be drawn in a clockwise direction instead. Drawing a reversed path could affect the appearance of a filled pattern, depending on the pattern and the fill rule in use.

The shape is created by reversing each whole or partial subpath in the path object individually.

See also
BezierPath::reversed

◆ reversed() [2/2]

Shape CeresEngine::Shape::reversed ( ) const &

Computes a shape containing the reversed contents of the current shape path objects.

The reversed shape does not necessarily have a different appearance when rendered. Instead, it changes the direction in which path segments are drawn. For example, reversing the path of a rectangle (whose line segments are normally drawn starting at the origin and proceeding in a counterclockwise direction) causes its line segments to be drawn in a clockwise direction instead. Drawing a reversed path could affect the appearance of a filled pattern, depending on the pattern and the fill rule in use.

The shape is created by reversing each whole or partial subpath in the path object individually.

See also
BezierPath::reversed

◆ stroke() [1/2]

void CeresEngine::Shape::stroke ( BezierPath &&  path,
const Paint paint,
double  lineWidth = 1.0,
BlendMode  blendMode = BlendMode::Normal,
LineCapStyle  lineCapStyle = LineCapStyle::Butt,
LineJoinStyle  lineJoinStyle = LineJoinStyle::Miter,
double  miterLimit = 10.0 
)

Draws a line along the path using the given stroke color and drawing attributes.

The drawn line is centered on the path with its sides parallel to the path segment. This method uses the current drawing attributes associated with the receiver. If a particular attribute is not set for the receiver, this method uses the corresponding default attribute.

Parameters
pathThe path to be stroked.
paintThe paint to stroke the path with.

◆ stroke() [2/2]

void CeresEngine::Shape::stroke ( const BezierPath path,
const Paint paint,
double  lineWidth = 1.0,
BlendMode  blendMode = BlendMode::Normal,
LineCapStyle  lineCapStyle = LineCapStyle::Butt,
LineJoinStyle  lineJoinStyle = LineJoinStyle::Miter,
double  miterLimit = 10.0 
)

Draws a line along the path using the given stroke color and drawing attributes.

The drawn line is centered on the path with its sides parallel to the path segment. This method uses the current drawing attributes associated with the receiver. If a particular attribute is not set for the receiver, this method uses the corresponding default attribute.

Parameters
pathThe path to be stroked.
paintThe paint to stroke the path with.

◆ transform()

void CeresEngine::Shape::transform ( const AffineTransform &  aTransform)

Transforms all points in the shape using the specified transform.

This method applies the transform to the shape path's points immediately.

Parameters
aTransformThe transform to apply to the shape.
See also
BezierPath::transform

◆ transformed() [1/2]

Shape && CeresEngine::Shape::transformed ( const AffineTransform &  aTransform) &&
inline

Transforms all points in the shape using the specified transform.

This method applies the transform to the shape path's points immediately.

Parameters
aTransformThe transform to apply to the shape.
See also
BezierPath::transform

◆ transformed() [2/2]

Shape CeresEngine::Shape::transformed ( const AffineTransform &  aTransform) const &

Transforms all points in the shape using the specified transform.

This method applies the transform to the shape path's points immediately.

Parameters
aTransformThe transform to apply to the shape.
See also
BezierPath::transform

Member Data Documentation

◆ mElements

Deque<Element, AnyAllocator> CeresEngine::Shape::mElements {gDefaultAllocator()}
private

A vector of all elements in the shape.

◆ mPaths

Deque<BezierPath, AnyAllocator> CeresEngine::Shape::mPaths {gDefaultAllocator()}
private

A vector that stores a unique copy of each path.


The documentation for this class was generated from the following file: