cugl::Scissor Class Reference

#include <CUScissor.h>

Public Member Functions
	Scissor ()
	Scissor (const Scissor &mask)
	Scissor (Scissor &&mask)
	~Scissor ()
void	dispose ()
bool	init (const Size size, float fringe=0.5)
bool	init (const Rect rect, float fringe=0.5)
bool	init (const Size size, const Affine2 &aff, float fringe=0.5)
bool	init (const Rect rect, const Affine2 &aff, float fringe=0.5)
bool	init (const Size size, const Mat4 &mat, float fringe=0.5)
bool	init (const Rect rect, const Mat4 &mat, float fringe=0.5)
bool	init (const std::shared_ptr< Scissor > &mask)
Scissor &	operator= (const Scissor &mask)
Scissor &	operator= (Scissor &&mask)
Scissor &	operator= (const Rect rect)
Scissor &	set (const Scissor &mask)
Scissor &	set (const std::shared_ptr< Scissor > &mask)
Scissor &	set (const Rect rect, float fringe=0.5)
Scissor &	set (const Rect rect, const Affine2 &aff, float fringe=0.5)
Scissor &	set (const Rect rect, const Mat4 &mat, float fringe=0.5)
Scissor &	setZero ()
Affine2	getTransform () const
void	setTransform (const Affine2 &transform)
void	setTransform (const Mat4 &transform)
Rect	getBounds () const
void	setBounds (const Rect bounds)
float	getFringe () const
void	setFringe (float fringe)
Scissor &	rotate (float angle)
Scissor &	scale (float value)
Scissor &	scale (const Vec2 s)
Scissor &	scale (float sx, float sy)
Scissor &	translate (const Vec2 t)
Scissor &	translate (float tx, float ty)
Scissor &	multiply (const Mat4 &mat)
Scissor &	multiply (const Affine2 &aff)
Scissor &	operator*= (const Mat4 &mat)
Scissor &	operator*= (const Affine2 &aff)
Scissor	operator* (const Mat4 &mat) const
Scissor	operator* (const Affine2 &aff) const
Scissor &	intersect (const Scissor &mask, bool loose=true)
Scissor	getIntersection (const Scissor &mask, bool loose=true) const
Scissor &	intersect (const std::shared_ptr< Scissor > &mask, bool loose)
std::shared_ptr< Scissor >	getIntersection (const std::shared_ptr< Scissor > &mask, bool loose) const
float *	getData (float *array) const
float *	getComponents (float *array) const
std::string	toString (bool verbose=false) const
	operator std::string () const

Static Public Member Functions
static std::shared_ptr< Scissor >	alloc (const Size size, float fringe=0.5)
static std::shared_ptr< Scissor >	alloc (const Rect rect, float fringe=0.5)
static std::shared_ptr< Scissor >	alloc (const Size size, const Affine2 &aff, float fringe=0.5)
static std::shared_ptr< Scissor >	alloc (const Rect rect, const Affine2 &aff, float fringe=0.5)
static std::shared_ptr< Scissor >	alloc (const Size size, const Mat4 &mat, float fringe=0.5)
static std::shared_ptr< Scissor >	alloc (const Rect rect, const Mat4 &mat, float fringe=0.5)
static std::shared_ptr< Scissor >	alloc (const std::shared_ptr< Scissor > &mask)

Detailed Description

This class defines a general purpose scissor mask.

A scissor mask is used to prevent portions of a 2d shape from showing. The mask is a transformed rectangle, and any pixel outside of this region is dropped. Unlike Gradient, a scissor is applied to a region of the framebuffer and is not a texture that can be applied to a surface. Therefore, the scissor mask region must be defined in terms of pixels (or at least in the same coordinate system as the vertices it is masking).

A scissor mask is defined by three values (in terms of largest to smallest data):

• An affine transform (for offset and rotation)
• A size vector for the extent
• A "fringe" value for edge aliasing

Unpacking this data into std140 format is a 16 element array of floats (the fringe is expanded into a per-axis value for the shader). And this is the format that this data is represented in the getData method so that it can be passed to a UniformBuffer for improved performance. It is also possible to get access to the individual components of the scissor mask, to pass them to a shader directly (though the transform must be inverted first if it is passed directly).

Scissor masks can be intersected. However, a scissor mask must always be a transformed rectangle, and not all quadrilateral intersections are guaranteed to be transformed rectangles. Therefore, these intersections are always an an approximation, with the intersecting scissor mask converted into an axis-aligned rectangle in the coordinate space of the current scissor mask. The affect is the same as the Rect#inscribe operation in in Rect.

Constructor & Destructor Documentation

Scissor() [1/3]

cugl::Scissor::Scissor

(

)

Creates a degenerate scissor of size 0.

All pixels will be dropped by this mask.

Scissor() [2/3]

cugl::Scissor::Scissor ( const Scissor &  mask )

inline

Creates a copy of the given scissor mask.

Parameters

mask	The scissor mask to copy

Scissor() [3/3]

cugl::Scissor::Scissor

(

Scissor &&

mask

)

Creates a copy with the resources of the given scissor mask.

The original scissor mask is no longer safe to use after calling this constructor.

Parameters

mask	The scissor mask to take from

~Scissor()

cugl::Scissor::~Scissor ( )

inline

Deletes this scissor mask, releasing all resources.

Member Function Documentation

alloc() [1/7]

static std::shared_ptr<Scissor> cugl::Scissor::alloc ( const Rect  rect, const Affine2 &  aff, float  fringe = 0.5  )

inlinestatic

Returns a new scissor with the given transformed bounds and fringe.

The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

Parameters

rect	The scissor mask bounds
aff	The scissor mask transform
fringe	The size of the scissor border in pixels

Returns

a new scissor with the given transformed bounds and fringe.

alloc() [2/7]

static std::shared_ptr<Scissor> cugl::Scissor::alloc ( const Rect  rect, const Mat4 &  mat, float  fringe = 0.5  )

inlinestatic

Returns a new scissor with the given transformed bounds and fringe.

The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

All z-components from the given matrix transform are lost.

Parameters

rect	The scissor mask bounds
mat	The scissor mask transform
fringe	The size of the scissor border in pixels

Returns

a new scissor with the given transformed bounds and fringe.

alloc() [3/7]

static std::shared_ptr<Scissor> cugl::Scissor::alloc ( const Rect  rect, float  fringe = 0.5  )

inlinestatic

Returns a new scissor with the given bounds and fringe.

The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

Parameters

rect	The scissor mask bounds
fringe	The size of the scissor border in pixels

Returns

a new scissor with the given bounds and fringe.

alloc() [4/7]

static std::shared_ptr<Scissor> cugl::Scissor::alloc ( const Size  size, const Affine2 &  aff, float  fringe = 0.5  )

inlinestatic

Returns a new scissor with the given transformed bounds and fringe.

The bounding box will have origin (0,0). The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

Parameters

size	The scissor mask size
aff	The scissor mask transform
fringe	The size of the scissor border in pixels

Returns

a new scissor with the given transformed bounds and fringe.

alloc() [5/7]

static std::shared_ptr<Scissor> cugl::Scissor::alloc ( const Size  size, const Mat4 &  mat, float  fringe = 0.5  )

inlinestatic

Returns a new scissor with the given transformed bounds and fringe.

The bounding box will have origin (0,0). The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

All z-components from the given matrix transform are lost.

Parameters

size	The scissor mask size
mat	The scissor mask transform
fringe	The size of the scissor border in pixels

Returns

a new scissor with the given transformed bounds and fringe.

alloc() [6/7]

static std::shared_ptr<Scissor> cugl::Scissor::alloc ( const Size  size, float  fringe = 0.5  )

inlinestatic

Returns a new scissor with the given bounds and fringe.

The bounding box will have origin (0,0). The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

Parameters

size	The scissor mask size
fringe	The size of the scissor border in pixels

Returns

a new scissor with the given bounds and fringe.

alloc() [7/7]

static std::shared_ptr<Scissor> cugl::Scissor::alloc ( const std::shared_ptr< Scissor > &  mask )

inlinestatic

Returns a new scissor mask that is a copy of the other.

Parameters

mask	The scissor mask to copy

Returns

a new scissor mask that is a copy of the other.

dispose()

void cugl::Scissor::dispose

(

)

Deletes the scissor mask and resets all attributes.

You must reinitialize the scissor mask to use it.

getBounds()

Rect cugl::Scissor::getBounds ( ) const

inline

Returns the bounding box of this scissor mask

The bounding box is axis-aligned. It ignored the transform component of the scissor mask.

Returns

the bounding box of this scissor mask

getComponents()

float* cugl::Scissor::getComponents

(

float *

array

)

const

Reads the scissor mask into the provided array

The scissor mask is written to the array so that it can be passed the the shader one component at a time (e.g. NOT in std140 format). It differs from getData in that it only uses 9 floats for the affine transform (as a 3x3 homogenous matrix).

Parameters

array

The array to store the values

Returns

a reference to the array for chaining

getData()

float* cugl::Scissor::getData

(

float *

array

)

const

Reads the scissor mask into the provided array

The scissor mask is written to the given array in std140 format. That is (1) 12 floats for the affine transform (as a 3x3 homogenous matrix), (2) 2 floats for the extent, and (3) 2 floats for the fringe (one for each axis). Values are written in this order.

Parameters

array

The array to store the values

Returns

a reference to the array for chaining

getFringe()

float cugl::Scissor::getFringe ( ) const

inline

Returns the edge fringe of this scissor mask

The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

Returns

the edge fringe of this scissor mask

getIntersection() [1/2]

Scissor cugl::Scissor::getIntersection	(	const Scissor &	mask,
		bool	loose = true
	)		const

Returns the intersection of the given scissor mask with this one.

The intersection will take place in the coordinate system of this scissor mask. The other mask will be transformed to be in this coordinate space. The transformation of mask will produce a rectangle inscribed in the transformed original. The parameter loose is the same as in the method Rect#inscribe.

This scissor mask will not be affected by this method.

Parameters

mask	The scissor mask to intersect with this one
loose	Whether to loosely inscribe the second mask on transformation

Returns

the intersection of the given scissor mask with this one.

getIntersection() [2/2]

std::shared_ptr<Scissor> cugl::Scissor::getIntersection	(	const std::shared_ptr< Scissor > &	mask,
		bool	loose
	)		const

Returns the intersection of the given scissor mask with this one.

The intersection will take place in the coordinate system of this scissor mask. The other mask will be transformed to be in this coordinate space. The transformation of mask will produce a rectangle inscribed in the transformed original. The parameter loose is the same as in the method Rect#inscribe.

This scissor mask will not be affected by this method.

Parameters

mask	The scissor mask to intersect with this one
loose	Whether to loosely inscribe the second mask on transformation

Returns

the intersection of the given scissor mask with this one.

getTransform()

Affine2 cugl::Scissor::getTransform ( ) const

inline

Returns the transform component of this scissor mask

If the scissor mask is not rotated or otherwise transformed, this value will be the identity.

This value only contains the transform on the scissor mask bounding box. It is not the same as the scissor matrix in a scissor shader. Do not pass this information directly to the shader. Use either the method getData or getComponents depending on whether or not you need std140 representation.

Returns

the transform component of this scissor mask

init() [1/7]

bool cugl::Scissor::init	(	const Rect	rect,
		const Affine2 &	aff,
		float	fringe = 0.5
	)

Initializes a scissor with the given transformed bounds and fringe.

The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

Parameters

rect	The scissor mask bounds
aff	The scissor mask transform
fringe	The size of the scissor border in pixels

Returns

true if initialization was successful.

init() [2/7]

bool cugl::Scissor::init	(	const Rect	rect,
		const Mat4 &	mat,
		float	fringe = 0.5
	)

Initializes a scissor with the given transformed bounds and fringe.

The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

All z-components from the given matrix transform are lost.

Parameters

rect	The scissor mask bounds
mat	The scissor mask transform
fringe	The size of the scissor border in pixels

Returns

true if initialization was successful.

init() [3/7]

bool cugl::Scissor::init	(	const Rect	rect,
		float	fringe = 0.5
	)

Initializes a scissor with the given bounds and fringe.

The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

Parameters

rect	The scissor mask bounds
fringe	The size of the scissor border in pixels

Returns

true if initialization was successful.

init() [4/7]

bool cugl::Scissor::init ( const Size  size, const Affine2 &  aff, float  fringe = 0.5  )

inline

Initializes a scissor with the given transformed bounds and fringe.

The bounding box will have origin (0,0). The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

Parameters

size	The scissor mask size
aff	The scissor mask transform
fringe	The size of the scissor border in pixels

Returns

true if initialization was successful.

init() [5/7]

bool cugl::Scissor::init ( const Size  size, const Mat4 &  mat, float  fringe = 0.5  )

inline

Initializes a scissor with the given transformed bounds and fringe.

The bounding box will have origin (0,0). The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

All z-components from the given matrix transform are lost.

Parameters

size	The scissor mask size
mat	The scissor mask transform
fringe	The size of the scissor border in pixels

Returns

true if initialization was successful.

init() [6/7]

bool cugl::Scissor::init ( const Size  size, float  fringe = 0.5  )

inline

Initializes a scissor with the given size and fringe.

The bounding box will have origin (0,0). The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

Parameters

size	The scissor mask size
fringe	The size of the scissor border in pixels

Returns

true if initialization was successful.

init() [7/7]

bool cugl::Scissor::init

(

const std::shared_ptr< Scissor > &

mask

)

Initializes this scissor mask to be a copy of the other.

Parameters

mask	The scissor mask to copy

Returns

true if initialization was successful.

intersect() [1/2]

Scissor& cugl::Scissor::intersect	(	const Scissor &	mask,
		bool	loose = true
	)

Intersects the given scissor mask with this one.

The intersection will take place in the coordinate system of this scissor mask. The other mask will be transformed to be in this coordinate space. The transformation of mask will produce a rectangle inscribed in the transformed original. The parameter loose is the same as in the method Rect#inscribe.

Parameters

mask	The scissor mask to intersect with this one
loose	Whether to loosely inscribe the second mask on transformation

Returns

a reference to the scissor for chaining

intersect() [2/2]

Scissor& cugl::Scissor::intersect ( const std::shared_ptr< Scissor > &  mask, bool  loose  )

inline

Intersects the given scissor mask with this one.

The intersection will take place in the coordinate system of this scissor mask. The other mask will be transformed to be in this coordinate space. The transformation of mask will produce a rectangle inscribed in the transformed original. The parameter loose is the same as in the method Rect#inscribe.

Parameters

mask	The scissor mask to intersect with this one
loose	Whether to loosely inscribe the second mask on transformation

Returns

a reference to the scissor for chaining

multiply() [1/2]

Scissor& cugl::Scissor::multiply ( const Affine2 &  aff )

inline

Applies the given transform to this scissor mask.

The matrix transform is applied after the existing scissor transform (which is natural, since the transform defines the initial box bounds). To pre-multiply a transform, set the transform directly.

Parameters

aff	The matrix to multiply by.

Returns

A reference to this (modified) scissor mask for chaining.

multiply() [2/2]

Scissor& cugl::Scissor::multiply ( const Mat4 &  mat )

inline

Applies the given transform to this scissor mask.

This transform is applied after the existing gradient transform (which is natural, since the transform defines the gradient shape). To pre-multiply a transform, set the transform directly.

Parameters

mat	The matrix to multiply by.

Returns

A reference to this (modified) scissor mask for chaining.

operator std::string()

cugl::Scissor::operator std::string ( ) const

inline

Cast from Scissor to a string.

operator*() [1/2]

Scissor cugl::Scissor::operator* ( const Affine2 &  aff ) const

inline

Returns a copy of the scissor mask transformed by the given matrix.

The matrix transform is applied after the existing scissor transform (which is natural, since the transform defines the initial box bounds). To pre-multiply a transform, set the transform directly.

Note: This does not modify the scissor mask.

Parameters

aff	The transform to multiply by.

Returns

a copy of the scissor mask transformed by the given matrix.

operator*() [2/2]

Scissor cugl::Scissor::operator* ( const Mat4 &  mat ) const

inline

Returns a copy of the scissor mask transformed by the given matrix.

The matrix transform is applied after the existing scissor transform (which is natural, since the transform defines the initial box bounds). To pre-multiply a transform, set the transform directly.

Note: This does not modify the scissor mask.

Parameters

mat	The transform to multiply by.

Returns

a copy of the scissor mask transformed by the given matrix.

operator*=() [1/2]

Scissor& cugl::Scissor::operator*=

(

const Affine2 &

aff

)

Applies the given transform to this scissor mask.

The matrix transform is applied after the existing scissor transform (which is natural, since the transform defines the initial box bounds). To pre-multiply a transform, set the transform directly.

Parameters

aff	The matrix to multiply by.

Returns

A reference to this (modified) scissor mask for chaining.

operator*=() [2/2]

Scissor& cugl::Scissor::operator*=

(

const Mat4 &

mat

)

Applies the given transform to this scissor mask.

This transform is applied after the existing gradient transform (which is natural, since the transform defines the gradient shape). To pre-multiply a transform, set the transform directly.

Parameters

mat	The matrix to multiply by.

Returns

A reference to this (modified) scissor mask for chaining.

operator=() [1/3]

Scissor& cugl::Scissor::operator= ( const Rect  rect )

inline

Sets this to be a scissor mask with the given bouding rectangle.

Any previous transforms are dropped when this operator is called.

Parameters

rect	The scissor mask bounds

Returns

this scissor mask, returned for chaining

operator=() [2/3]

Scissor& cugl::Scissor::operator= ( const Scissor &  mask )

inline

Sets this scissor mask to be a copy of the given one.

Parameters

mask	The scissor mask to copy

Returns

this scissor mask, returned for chaining

operator=() [3/3]

Scissor& cugl::Scissor::operator=

(

Scissor &&

mask

)

Sets this scissor mask to be have the resources of the given one.

The original scissor mask is no longer safe to use after calling this operator.

Parameters

mask	The scissor mask to take from

Returns

this scissor mask, returned for chaining

rotate()

Scissor& cugl::Scissor::rotate

(

float

angle

)

Applies a rotation to this scissor mask.

The rotation is in radians, counter-clockwise about the given axis.

Parameters

angle

The angle (in radians).

Returns

This scissor mask, after rotation.

scale() [1/3]

Scissor& cugl::Scissor::scale

(

const Vec2

s

)

Applies a non-uniform scale to this scissor mask.

Parameters

s	The vector storing the individual scaling factors

Returns

This scissor mask, after scaling.

scale() [2/3]

Scissor& cugl::Scissor::scale ( float  sx, float  sy  )

inline

Applies a non-uniform scale to this scissor mask.

Parameters

sx	The amount to scale along the x-axis.
sy	The amount to scale along the y-axis.

Returns

This scissor mask, after scaling.

scale() [3/3]

Scissor& cugl::Scissor::scale

(

float

value

)

Applies a uniform scale to this scissor mask.

Parameters

value

The scalar to multiply by.

Returns

This scissor mask, after scaling.

set() [1/5]

Scissor& cugl::Scissor::set	(	const Rect	rect,
		const Affine2 &	aff,
		float	fringe = 0.5
	)

Sets the scissor mask to have the given transformed bounds and fringe.

Any previous transforms are dropped when this method is called.

The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

Parameters

rect	The scissor mask bounds
aff	The scissor mask transform
fringe	The size of the scissor border in pixels

Returns

this scissor mask, returned for chaining

set() [2/5]

Scissor& cugl::Scissor::set	(	const Rect	rect,
		const Mat4 &	mat,
		float	fringe = 0.5
	)

Sets the scissor mask to have the given transformed bounds and fringe.

Any previous transforms are dropped when this method is called.

The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

All z-components from the given matrix transform are lost.

Parameters

rect	The scissor mask bounds
mat	The scissor mask transform
fringe	The size of the scissor border in pixels

Returns

this scissor mask, returned for chaining

set() [3/5]

Scissor& cugl::Scissor::set	(	const Rect	rect,
		float	fringe = 0.5
	)

Sets the scissor mask to have the given bounds and fringe.

Any previous transforms are dropped when this method is called.

The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

Parameters

rect	The scissor mask bounds
fringe	The size of the scissor border in pixels

Returns

this scissor mask, returned for chaining

set() [4/5]

Scissor& cugl::Scissor::set

(

const Scissor &

mask

)

Sets this scissor mask to be a copy of the given one.

Parameters

mask	The scissor mask to copy

Returns

this scissor mask, returned for chaining

set() [5/5]

Scissor& cugl::Scissor::set ( const std::shared_ptr< Scissor > &  mask )

inline

Sets this scissor mask to be a copy of the given one.

Parameters

mask	The scissor mask to copy

Returns

this scissor mask, returned for chaining

setBounds()

void cugl::Scissor::setBounds

(

const Rect

bounds

)

Sets the bounding box of this scissor mask

The bounding box is axis-aligned. It ignores the transform component of the scissor mask.

Parameters

bounds

The bounding box of this scissor mask

setFringe()

void cugl::Scissor::setFringe ( float  fringe )

inline

Sets the edge fringe of this scissor mask

The fringe is the size of the scissor border in pixels. A value less than 0 gives a sharp transition, where larger values have more gradual transitions.

Parameters

fringe

The edge fringe of this scissor mask

setTransform() [1/2]

void cugl::Scissor::setTransform

(

const Affine2 &

transform

)

Sets the transform component of this scissor mask

If the scissor mask is not rotated or otherwise transformed, this value should be the identity.

This value only contains the transform on the scissor mask bounding box. It is not the same as the scissor matrix in a scissor shader. Do not pass this information directly to the shader. Use either the method getData or getComponents depending on whether or not you need std140 representation.

Parameters

transform

The transform component of this scissor mask

setTransform() [2/2]

void cugl::Scissor::setTransform

(

const Mat4 &

transform

)

Sets the transform component of this scissor mask

If the scissor mask is not rotated or otherwise transformed, this value should be the identity.

This value only contains the transform on the scissor mask bounding box. It is not the same as the scissor matrix in a scissor shader. Do not pass this information directly to the shader. Use either the method getData or getComponents depending on whether or not you need std140 representation.

Parameters

transform

The transform component of this scissor mask

setZero()

Scissor& cugl::Scissor::setZero

(

)

Sets this to be a degenerate scissor of size 0.

All pixels will be dropped by this mask.

Returns

this scissor mask, returned for chaining

toString()

std::string cugl::Scissor::toString

(

bool

verbose = false

)

const

Returns a string representation of this scissor for debuggging purposes.

If verbose is true, the string will include class information. This allows us to unambiguously identify the class.

Parameters

verbose

Whether to include class information

Returns

a string representation of this scissor for debuggging purposes.

translate() [1/2]

Scissor& cugl::Scissor::translate

(

const Vec2

t

)

Applies a translation to this gradient.

Parameters

t	The vector storing the individual translation offsets

Returns

This scissor mask, after translation.

translate() [2/2]

Scissor& cugl::Scissor::translate ( float  tx, float  ty  )

inline

Applies a translation to this gradient.

Parameters

tx	The translation offset for the x-axis.
ty	The translation offset for the y-axis.

Returns

This scissor mask, after translation.

---

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

• include/cugl/render/CUScissor.h