cugl::graphics Namespace Reference

Namespaces
namespace	vulkan

Classes
class	AttributeDef
class	BlendState
class	ComputeShader
class	Font
class	FontLoader
class	FrameBuffer
class	GLSLConstant
class	GlyphRun
class	Gradient
class	GradientLoader
class	GraphicsShader
class	Image
class	ImageArray
class	IndexBuffer
class	Mesh
class	MeshExtruder
class	Particle3
class	ParticleEmitter
class	ParticleInstance
class	ParticleLoader
class	ParticleShader
class	ParticleSystem
class	ParticleVertex
class	RenderPass
class	ResourceDef
class	Sampler
class	Scissor
class	ShaderSource
class	SpriteBatch
class	SpriteMesh
class	SpriteMeshLoader
class	SpriteSheet
class	SpriteVertex
class	StencilState
class	StorageBuffer
class	TextLayout
class	Texture
class	TextureArray
class	TextureLoader
class	TextureRenderer
class	UniformBuffer
class	UniformDef
class	VertexBindInfo
class	VertexBuffer

Typedefs
typedef std::function< void(const ParticleEmitter &source, Particle3 *part)>	ParticleAllocator
typedef std::function< void(Particle3 *part)>	ParticleDeallocator
typedef std::function< bool(float delta, Particle3 *part, ParticleInstance *inst)>	ParticleUpdater

Enumerations
enum class	GLSLType : int {   NONE = 0 , INT = 1 , UINT = 2 , FLOAT = 3 ,   VEC2 = 4 , VEC3 = 5 , VEC4 = 6 , IVEC2 = 7 ,   IVEC3 = 8 , IVEC4 = 9 , UVEC2 = 10 , UVEC3 = 11 ,   UVEC4 = 12 , MAT2 = 13 , MAT3 = 14 , MAT4 = 15 ,   COLOR = 16 , UCOLOR = 17 , BLOCK = 18 }
enum class	BufferAccess {   STATIC = 0 , DYNAMIC = 1 , COMPUTE_ONLY = 2 , COMPUTE_READ = 3 ,   COMPUTE_ALL = 4 }
enum class	ShaderStage : int {   UNDEFINED , VERTEX , FRAGMENT , CONTROL ,   EVALUATION , GEOMETRY , COMPUTE , GRAPHICS ,   ALL }
enum class	ResourceType : int {   MONO_BUFFER = 0 , MULTI_BUFFER = 1 , MONO_STORAGE = 2 , MULTI_STORAGE = 3 ,   TEXTURE = 4 , TEXTURE_ARRAY = 5 , SAMPLER = 6 , IMAGE = 7 ,   IMAGE_ARRAY = 8 , COMPUTE_VERTEX = 9 , COMPUTE_INDEX = 10 , COMPUTE_STORAGE = 11 ,   COMPUTE_IMAGE = 12 }
enum class	DrawMode : int {   UNDEFINED = 0 , POINTS = 1 , LINES = 2 , LINE_STRIP = 3 ,   TRIANGLES = 4 , TRIANGLE_STRIP = 5 , TRIANGLE_FAN = 6 }
enum class	FrontFace : int { CCW = 0 , CW = 1 }
enum class	CullMode : int { NONE = 0 , FRONT = 1 , BACK = 2 , FRONT_BACK = 3 }
enum class	CompareOp : int {   NEVER = 0 , LESS = 1 , EQUAL = 2 , LESS_OR_EQUAL = 3 ,   GREATER = 4 , NOT_EQUAL = 5 , GREATER_OR_EQUAL = 6 , ALWAYS = 7 }
enum class	StencilMode : int {   NONE = 0 , CLIP = 1 , CLIP_CLEAR = 2 , MASK = 3 ,   MASK_CLEAR = 4 , STAMP = 5 , CLAMP = 6 , STAMP_EVENODD = 7 ,   STAMP_NONZERO = 8 , CLEAR = 9 }
enum class	StencilOp : int {   KEEP = 0 , ZERO = 1 , REPLACE = 2 , INCR_CLAMP = 3 ,   DECR_CLAMP = 4 , INVERT = 5 , INCR_WRAP = 6 , DECR_WRAP = 7 }
enum class	BlendMode : int {   SOLID = 0 , ADDITIVE = 1 , MULTIPLICATIVE = 2 , ALPHA = 3 ,   PREMULT = 4 , MAXIMUM = 5 , MINIMUM = 6 }
enum class	BlendFactor : int {   ZERO = 0 , ONE = 1 , SRC_COLOR = 2 , ONE_MINUS_SRC_COLOR = 3 ,   DST_COLOR = 4 , ONE_MINUS_DST_COLOR = 5 , SRC_ALPHA = 6 , ONE_MINUS_SRC_ALPHA = 7 ,   DST_ALPHA = 8 , ONE_MINUS_DST_ALPHA = 9 , CONSTANT_COLOR = 10 , ONE_MINUS_CONSTANT_COLOR = 11 ,   CONSTANT_ALPHA = 12 , ONE_MINUS_CONSTANT_ALPHA = 13 , SRC_ALPHA_SATURATE = 14 }
enum class	BlendEq : int {   ADD = 0 , SUBTRACT = 1 , REVERSE_SUBTRACT = 2 , MIN = 3 ,   MAX = 4 }
enum class	ImageAccess {   SHADER_ONLY = 0 , READ_ONLY = 1 , WRITE_ONLY = 2 , READ_WRITE = 3 ,   COMPUTE_ONLY = 4 , COMPUTE_READ = 5 , COMPUTE_ALL = 6 }
enum class	TexelFormat {   UNDEFINED = 0 , CUSTOM = 1 , COLOR_RGBA = 2 , COLOR_RGBA4 = 3 ,   COLOR_BGRA = 4 , COLOR_BGRA4 = 5 , COLOR_RGB = 6 , COLOR_RGB4 = 7 ,   COLOR_RG = 8 , COLOR_RG4 = 9 , COLOR_RED = 10 , DEPTH = 11 ,   STENCIL = 12 , DEPTH_STENCIL = 13 }
enum class	TextureFilter : int {   NEAREST = 0 , LINEAR = 1 , NEAREST_MIPMAP_NEAREST = 2 , LINEAR_MIPMAP_NEAREST = 3 ,   NEAREST_MIPMAP_LINEAR = 4 , LINEAR_MIPMAP_LINEAR = 5 }
enum class	TextureWrap : int { CLAMP = 0 , REPEAT = 1 , MIRROR = 2 , BORDER = 3 }
enum class	HorizontalAlign : int {   LEFT = 0 , CENTER = 1 , RIGHT = 2 , JUSTIFY = 3 ,   HARD_LEFT = 4 , TRUE_CENTER = 5 , HARD_RIGHT = 6 }
enum class	VerticalAlign {   BASELINE = 0 , BOTTOM = 1 , MIDDLE = 2 , TOP = 3 ,   HARD_BOTTOM = 4 , TRUE_MIDDLE = 5 , HARD_TOP = 6 }

Functions
int	operator* (Font::Style value)
Font::Style	operator| (Font::Style lhs, Font::Style rhs)
Font::Style	operator& (Font::Style lhs, Font::Style rhs)
Font::Style	operator^ (Font::Style lhs, Font::Style rhs)
Font::Style	operator~ (Font::Style lhs)
TextureFilter	json_filter (const std::string name)
TextureWrap	json_wrap (const std::string name)
BlendMode	json_blend_mode (std::string name)
Color4	json_color (JsonValue *entry, std::string backup)
void	sdl_flip_vertically (SDL_Surface *surf)
template<typename T >
void	parse_mesh (Mesh< T > &mesh, const std::shared_ptr< JsonValue > &json)

Detailed Description

The classes and functions needed to construct a graphics pipeline.

Initially these were part of the core CUGL module. However, in the transition to Vulkan, we discovered that we need to factor this out. This allows us to provide options for OpenGL, Vulkan, and even headless clients.

The classes and functions needed to construct a graphics pipeline.

Initially these were part of the core CUGL module (everyone wants graphics, right). However, after student demand for a headless option that did not have so many OpenGL dependencies, this was factored out.

Forward reference for now

Typedef Documentation

ParticleAllocator

cugl::graphics::ParticleAllocator

This type represents a function to allocate a Particle3 object.

Particle systems recycle their particle objects, so allocation simply means assigning attributes after they have been recycled. That is the purpose of this function. It takes a ParticleEmitter object and uses that to reassign the attributes of a Particle3 object.

This function is allowed to allocate and assign custom data to the userdata attribute in a particle. However, if it does so, the user should also create a ParticleDeallocator function to reclaim this memory as nessary.

The allocator should set all attributes except for distance and delay. Those attributes are managed by the ParticleSystem and any values set here will be overwritten.

This function type is equivalent to

 std::function<void(const ParticleEmitter& source, Particle3* part)>

Parameters

source	The particle emitter
part	The particle to update

ParticleDeallocator

cugl::graphics::ParticleDeallocator

This type represents a function to deallocate a Particle3 object.

Particle systems recycle their particle objects, and we need to be clean up any allocated memory when they are recycled. That is the purpose of this function. Note that this this function is only necessary is the ParticleAllocator allocated memory to the userdata attribute of a Particle3 object. Otherwise, it can be ignored.

The function type is equivalent to

 std::function<void(Particle3* part)>

Parameters

part	The particle to recycle

ParticleUpdater

cugl::graphics::ParticleUpdater

This type represents a function to update a Particle3 object.

This function provides the user-defined simulation for the particle system. It takes a Particle3 object and defines a ParticleInstance for rendering.

While this function should update the attributes of the Particle3, it is not necessary to update the life attribute, as that value is managed by the system. Any changes to that attribute will unnaturally shorten or lengthen the lifespan of the particle. In addition, any values set to distance and delay will be overwritten.

This function should return true if the update was successful. It should return false if the update failed and the particle should be deleted.

This function type is equivalent to

 std::function<bool(float delta, Particle3* part, ParticleInstance* inst)>

Parameters

delta	The time passed since the last call to update
part	The particle to simulate
inst	The object to hold the simulation results

Enumeration Type Documentation

BlendEq

enum class cugl::graphics::BlendEq : int

strong

An enum representing the color blending equation.

This enum is an abstraction of constants like GL_FUNC_ADD or the Vulkan equivalent VK_BLEND_OP_ADD.

Enumerator
ADD	Adds the scaled destination to the scaled source
SUBTRACT	Subtracts the scaled destination from the scaled source
REVERSE_SUBTRACT	Subtracts the scaled source from the scaled destination
MIN	Computes the min of each color value of the source and destination. Note that this equation ignores the color blend factor.
MAX	Computes the max of each color value of the source and destination. Note that this equation ignores the color blend factor.

BlendFactor

enum class cugl::graphics::BlendFactor : int

strong

An enum representing the color blending factor.

This enum is an abstraction of constants like GL_SRC_ALPHA or the Vulkan equivalent VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA. Note that blend factors have different meanings according to whether they are an RGB blend factor or an alpha blend factor.

In the documentation for each value, Rs is the red value of the source, while Rd is the red value of the destination (and similarly G green, B blue, and A alpha). Rc is the red of the constant color, which is a color set with the graphics pipeline.

Enumerator
ZERO	An RGB factor (0,0,0), and an alpha factor of 0
ONE	An RGB factor (1,1,1), and an alpha factor of 1
SRC_COLOR	An RGB factor (Rs,Gs,Bs), and an alpha factor of As
ONE_MINUS_SRC_COLOR	An RGB factor (1-Rs,1-Gs,1-Bs), and an alpha factor of 1-As
DST_COLOR	An RGB factor (Rd,Gd,Bd), and an alpha factor of Ad
ONE_MINUS_DST_COLOR	An RGB factor (1-Rd,1-Gd,1-Bd), and an alpha factor of 1-Ad
SRC_ALPHA	An RGB factor (As,As,As), and an alpha factor of As
ONE_MINUS_SRC_ALPHA	An RGB factor (1-As,1-As,1-As), and an alpha factor of 1-As
DST_ALPHA	An RGB factor (Ad,Ad,Ad), and an alpha factor of Ad
ONE_MINUS_DST_ALPHA	An RGB factor (1-Ad,1-Ad,1-Ad), and an alpha factor of 1-Ad
CONSTANT_COLOR	An RGB factor (Rc,Gc,Bc), and an alpha factor of Ac
ONE_MINUS_CONSTANT_COLOR	An RGB factor (1-Rc,1-Gc,1-Bc), and an alpha factor of 1-Ac
CONSTANT_ALPHA	An RGB factor (Ac,Ac,Ac), and an alpha factor of Ac
ONE_MINUS_CONSTANT_ALPHA	An RGB factor (1-Ac,1-Ac,1-Ac), and an alpha factor of 1-Ac
SRC_ALPHA_SATURATE	An RGB factor (f,f,f) where f = min(As,1-Ad), and an alpha factor of 1

BlendMode

enum class cugl::graphics::BlendMode : int

strong

An enum of predefined color blend models

While it is possible to define custom color blending via BlendState, there are some fairly common blend modes that most applications will use. This enum represents those modes to make it easier on the developer to use the color blending.

Enumerator
SOLID	Later color values replace previous ones.
ADDITIVE	Later color values are added to previous ones.
MULTIPLICATIVE	Later color values are mutliplied with previous ones.
ALPHA	Later color values are blended using (non-premultiplied) alpha
PREMULT	Later color values are blended using premultiplied alpha
MAXIMUM	Color values are maximum of all applied color values.
MINIMUM	Color values are minimum of all applied color values.

BufferAccess

enum class cugl::graphics::BufferAccess

strong

This enum represents the different buffer access types

A buffer can be any of VertexBuffer, IndexBuffer, UniformBuffer or StorageBuffer. These types are a simplification of the buffer types provided by the various graphics APIs. We find that they are sufficient for most of our purposes.

Enumerator
STATIC	A write-only buffer that never changes. Buffers created with this type will only respond to an initial call to load data. All other attempts to load to this buffer will fail.
DYNAMIC	A write-only buffer that changes often. Buffers created with this type may be updated every animation frame. Note, however, that it is not safe to update such a buffer more than once a frame, as that can interfere with drawing calls. Once the initial drawing call is made, all changes should cease.
COMPUTE_ONLY	A buffer that can be updated by a compute shader VULKAN ONLY: Buffers created with this type can be the output of a compute shader, and then used as input to a graphics shader. However, the results of the compute shader may not be accessed on the CPU side.
COMPUTE_READ	A buffer that can be updated by a compute shader and read on the CPU side VULKAN ONLY: Buffers created with this type can be the output of a compute shader, and then used as input to a graphics shader. In addition, it is possible to read the compute shader results on the CPU side.
COMPUTE_ALL	The buffer has full compute and CPU access. Vulkan ONLY: Buffers created with this type can be the output of a compute shader, and then used as input to a graphics shader. In addition, they can be both read and write on the CPU side.

CompareOp

enum class cugl::graphics::CompareOp : int

strong

An enum representing comparison operators for depth and stencil tests.

This enum is an abstraction of constants like GL_NEVER or the Vulkan equivalent VK_COMPARE_OP_NEVER.

Enumerator
NEVER	The comparison test always fails
LESS	The comparison tests succeeds if reference < test
EQUAL	The comparison tests succeeds if reference == test
LESS_OR_EQUAL	The comparison tests succeeds if reference <= test
GREATER	The comparison tests succeeds if reference > test
NOT_EQUAL	The comparison tests succeeds if reference != test
GREATER_OR_EQUAL	The comparison tests succeeds if reference >= test
ALWAYS	The comparison test always succeeds

CullMode

enum class cugl::graphics::CullMode : int

strong

An enum representing the current cull mode.

Culling is used to remove non-visible triangles. This enum is an abstraction of constants like GL_BACK or the Vulkan equivalent VK_CULL_MODE_BACK_BIT. Note that culling only applies to triangles, not points or lines.

Enumerator
NONE	No triangle culling is performed
FRONT	Forward facing triangles are culled
BACK	Backwards facing triangles are culled
FRONT_BACK	All triangles are culled (but lines and points are drawn)

DrawMode

enum class cugl::graphics::DrawMode : int

strong

An enum representing the current drawing command.

We only support drawing commands supported by both OpenGL and Vulkan. This enum is an abstraction of contants like GL_TRIANGLES or the Vulkan equivalent VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST.

Enumerator
UNDEFINED	An undefined draw mode
POINTS	Draw a sequence of points
LINES	Draw a sequence of line segment pairs
LINE_STRIP	Draw an OpenGL line segment strip
TRIANGLES	Draw a sequence of triangles defined as vertex triplets
TRIANGLE_STRIP	Draw an OpenGL triangle strip
TRIANGLE_FAN	Draw an OpenGL triangle fan

FrontFace

enum class cugl::graphics::FrontFace : int

strong

An enum defining the current facing of triangles/polygons.

This enum is an abstraction of constants like GL_CCW or the Vulkan equivalent VK_FRONT_FACE_COUNTER_CLOCKWISE.

Enumerator
CCW	Counter-clockwise triangles are forward facing
CW	Clockwise triangles are forward facing

GLSLType

enum class cugl::graphics::GLSLType : int

strong

An enum representing the supported GLSL types.

This enum is used to connect C++ types to GLSL types. Note that not all platforms support all types (particularly the user-defined BLOCK type.

Enumerator
NONE	Void type
INT	32-bit signed int type
UINT	32-bit unsigned int type
FLOAT	32-bit float type
VEC2	Two-element float vector
VEC3	Three-element float vector
VEC4	Four-element float vector
IVEC2	Two-element signed int vector
IVEC3	Three-element signed int vector
IVEC4	Four-element signed int vector
UVEC2	Two-element unsigned int vector
UVEC3	Three-element unsigned int vector
UVEC4	Four-element unsigned int vector
MAT2	2x2 float matrix
MAT3	3x3 float matrix
MAT4	4x4 float matrix
COLOR	4 element float color
UCOLOR	32-bit int color
BLOCK	User-defined struct

HorizontalAlign

enum class cugl::graphics::HorizontalAlign : int

strong

This enumeration represents the horizontal alignment of each line of text.

The horizontal alignment has two meanings. First, it is the relationship of the relative alignment of multiple lines. In addition, it defines the x-coordinate origin of the text layout. The later is relevant even when the text layout is a single line.

Enumerator
LEFT	Anchors the each line on the natural left side (DEFAULT) The x-coordinate origin will be the left side of each line of text, and all lines of text will be aligned at this point. If the initial character of a line of text has any natural spacing on the left-hand side (e.g the character width is less than the advance), this will be included.
CENTER	Anchors each line of text in the natural center. The x-coordinate origin with the be the center of each line of text, and lines of text will all be centered at this point. Centering will include any natural spacing (e.g the character width is less than the advance) around the first and last character.
RIGHT	Anchors each line of text on the natural right side The x-coordinate origin will be the right side of each line of text, and all lines of text will be aligned at this point. If the final character of a line of text has any natural spacing on the right-hand side (e.g the character width is less than the advance), this will be included.
JUSTIFY	Justifies each line of text. Justification means that each line of text is flush on both the left and right sides (including any natural spacing around the first and last character of each line). This will involve introducing additional white space, as well as spaces between characters if the attribute Font#getStretchLimit is non-zero. When this option is chosen, the x-coordinate origin is on the natural left side.
HARD_LEFT	Anchors the each line on the visible left side The x-coordinate origin will be the left side of each line of text, and all lines of text will be aligned at this point. If the initial character of a line of text has any natural spacing on the left-hand side (e.g the character width is less than the advance), this will be ignored. Hence the left edge of the first character of each line will visibly align.
TRUE_CENTER	Anchors each line of text in the visible center. The x-coordinate origin with the be the center of each line of text, and lines of text will all be centered at this point. Centering will ignore any natural spacing (e.g the character width is less than the advance) around the first and last character. Hence the text will be measured from the left edge of the first character to the right edge of the second.
HARD_RIGHT	Anchors the each line on the visible right side The x-coordinate origin will be the right side of each line of text, and all lines of text will be aligned at this point. If the final character of a line of text has any natural spacing on the right-hand side (e.g the character width is less than the advance), this will be ignored. Hence the right edge of the last character of each line will visibly align.

ImageAccess

enum class cugl::graphics::ImageAccess

strong

An enum defining the access rules for and image.

Access rules apply to the methods Image#set and Image#get. They also indicate whether the image can be used in a compute shader or not. It is assumed that all images can be sampled by a shader.

Enumerator
SHADER_ONLY	The image can only be used in shader. The image does not support read or write access. This format is useful for images that associated with a FrameBuffer and support post-processing effects.
READ_ONLY	This image is read only on the CPU side. The image supports Image#get in addition to being accessed by a shader.
WRITE_ONLY	The image is write-only on the CPU side. While the image can be accessed by a shader, no data can be loaded into the image after it is initialized. However, it is possible to add new data on the CPU side via Image#set.
READ_WRITE	The image supports full CPU read and write access Both methods Image#set and Image#get are supported.
COMPUTE_ONLY	The image can be accessed by a computer shader but has no CPU access. Vulkan ONLY: Neither methods Image#set nor Image#get are supported. However, the image can be updated by a compute shader.
COMPUTE_READ	The image can be accessed by a computer shader and read from the CPU. Vulkan ONLY: The method Image#get is supported, but the image can only be updated by a compute shader.
COMPUTE_ALL	The image has full compute and CPU access. Vulkan ONLY: The methods Image#get and Image#set are both supported. In addition, the image can be updated by a compute shader.

ResourceType

enum class cugl::graphics::ResourceType : int

strong

An enum representing a shader resource (buffer or texture).

Resources are any value attached to a shader that cannot be represented as GLSL primitive type. These primarily include textures and uniform buffers. However, in the case of Vulkan, there is a wider array of types supported. See the documentation for each enum value for the supported types.

Enumerator
MONO_BUFFER	A uniform buffer that is composed of just one block OpenGL and Vulkan: This type is supported in both APIs. It corresponds to a uniform buffer that has only one block, which cannot change during drawing. It corresponds to type uniform in GLSL. Note that this restriction is only on the number of blocks. It says nothing about the read/write access to the buffer itself. It is possible to have a dynamic (read/write) uniform buffer with just one block.
MULTI_BUFFER	A uniform buffer that is composed of multiple blocks OpenGL and Vulkan: This type is supported in both APIs. It corresponds to a buffer that can vary the block between drawing calls. It corresponds to type uniform in GLSL. Note that this restriction is only on the number of blocks. It says nothing about the read/write access to the buffer itself. It is possible to have a static (write-once) uniform buffer with mutliple blocks.
MONO_STORAGE	A storage buffer that is composed of just one block Vulkan ONLY: This type corresponds to a storage buffer that has only one block, which cannot change during shader executions. It is supported by both graphics and compute shaders in Vulkan, but attempts to use this resource with OpenGL will fail. It corresponds to type buffer in GLSL. Note that this restriction is only on the number of blocks. It says nothing about the read/write access to the buffer itself. It is possible to have a dynamic (read/write) storage buffer with just one block.
MULTI_STORAGE	A storage buffer that is composed of multiple blocks Vulkan ONLY: This type corresponds to a storage buffer that has only multiple blocks that can vary between shader executions. It is supported by both graphics and compute shaders in Vulkan, but attempts to use this resource with OpenGL will fail. It corresponds to type buffer in GLSL. Note that this restriction is only on the number of blocks. It says nothing about the read/write access to the buffer itself. It is possible to have a static (write-once) storage buffer with mutliple blocks.
TEXTURE	A (2d) texture with sampler OpenGL and Vulkan: In OpenGL, this resource is a standard GL_TEXTURE_2D object. In Vulkan, it is a combined image and sampler. It corresponds to type sampler2D in GLSL.
TEXTURE_ARRAY	A (2d) texture array with sampler OpenGL and Vulkan: In OpenGL, this resource is a GL_TEXTURE_2D_ARRAY object. In Vulkan, it is a combined image array and sampler (there is only one sampler for the entire array). It corresponds to sampler2DArray in GLSL.
SAMPLER	A sampler object Vulkan ONLY: Only Vulkan supports separating samplers from textures. Attempts to use this resource with OpenGL will fail. It corresponds to type sampler in GLSL.
IMAGE	An image object Vulkan ONLY: An image object is a texture without a sampler. Only Vulkan supports this separation. Attempts to use this resource with OpenGL will fail. It corresponds to type texture2D in GLSL.
IMAGE_ARRAY	An image array object Vulkan ONLY: An image array is a texture array without a sampler. Only Vulkan supports this separation. Attempts to use this resource with OpenGL will fail. It corresponds to type texture2DArray in GLSL.
COMPUTE_VERTEX	A vertex buffer that is the output to a compute shader Vulkan ONLY: This is a VertexBuffer with a compute type such as BufferAccess#COMPUTE_ONLY or similar. It can be used as a storage buffer in a compute shader, and a vertex buffer in a graphics shader.
COMPUTE_INDEX	A vertex buffer that is the output to a compute shader Vulkan ONLY: This is a IndexBuffer with a compute type such as BufferAccess#COMPUTE_ONLY or similar. It can be used as a storage buffer in a compute shader, and an index buffer in a graphics shader.
COMPUTE_STORAGE	A storage buffer that is the output to a compute shader Vulkan ONLY: This is a StorageBuffer with a compute type such as BufferAccess#COMPUTE_ONLY or similar. It can be used as a storage buffer in both a compute shader, and a graphics shader. This value should only be used for outputs to a compute shader. Inputs should use type MONO_STORAGE.
COMPUTE_IMAGE	An image that is the output to a compute shader Vulkan ONLY: The is a Image with an access type such as ImageAccess#COMPUTE_ONLY on similar. It can be used as a storage image in a compute shader, and a sampled image in a graphics shader. It corresponds to uniform image2D in GLSL. This value should only be used for outputs to a compute shader. Inputs should use type Image.

ShaderStage

enum class cugl::graphics::ShaderStage : int

strong

An enum representing the various stages of the graphics pipeline.

This enum is used to refer to elements of a GLSL shader. In particular, it references which file to look for a variable. Note that only the first two stages are supported by OpenGL/OpenGLES.

Enumerator
UNDEFINED	An undefined shader stage
VERTEX	The vertex shader stage (.vert)
FRAGMENT	The fragment shader stage (.frag)
CONTROL	The tesselation control shader stage (.tcl, VULKAN ONLY)
EVALUATION	The tesselation evalation shader stage (.tel, VULKAN ONLY)
GEOMETRY	The geometry shader stage (.geom, VULKAN ONLY)
COMPUTE	The compute shader stage (.comp, VULKAN ONLY)
GRAPHICS	All active graphics stages (excluding compute)
ALL	All active stages (including compute)

StencilMode

enum class cugl::graphics::StencilMode : int

strong

An enum of predefined stencil tests.

While it is possible to define custom stencil tests via StencilState, there are some fairly common stencil tests that most applications will use. This enum represents those tests to make it easier on the developer to use the stencil buffer.

Enumerator
NONE	Disables any stencil effects. This effect directs the pipeline to ignore the stencil buffer when drawing. However, it does not clear the contents.
CLIP	Restricts all drawing to a stenciled region. In order for this effect to do anything, you must have created a stencil region with StencilMode#STAMP or one of its variants. This effect will process the drawing commands normally, but restrict all drawing to the stenciled region. This can be used to draw non-convex shapes by making a stencil and drawing a rectangle over the stencil.
CLIP_CLEAR	Restricts all drawing to the stenciled region. In order for this effect to do anything, you must have created a stencil region with StencilMode#STAMP or one of its variants. This effect will process the drawing commands normally, but restrict all drawing to the stenciled region. This can be used to draw non-convex shapes by making a stencil and drawing a rectangle over the stencil. This mode is different from StencilMode#CLIP in that it will zero out the pixels it draws in the stencil buffer, effectively removing them from the stencil region. In many applications, this is a way to clear the stencil buffer once it is no longer needed (especially if depth and stencil are unified in the same attachment).
MASK	Prohibits all drawing to the stenciled region. In order for this effect to do anything, you must have created a stencil region with StencilMode#STAMP or one of its variants. This effect will process the drawing commands normally, but reject any attempts to draw to the stenciled region. This can be used to draw shape borders on top of a solid shape.
MASK_CLEAR	Prohibits all drawing to the stenciled region. In order for this effect to do anything, you must have created a stencil region with StencilMode#STAMP or one of its variants. This effect will process the drawing commands normally, but reject any attempts to draw to the stenciled region. This can be used to draw shape borders on top of a solid shape. This mode is different from StencilMode#CLIP in that it will zero out the pixels it draws in the stencil buffer, effectively removing them from the stencil region. In many applications, this is a way to clear the stencil buffer once it is no longer needed (especially if depth and stencil are unified in the same attachment).
STAMP	Adds a stencil region the buffer This effect will not have any immediate visible effects. Instead it creates a stencil region for modes such as StencilMode#CLIP, StencilMode#MASK, and the like. The shapes are drawn to the stencil buffer additively to the buffer. It ignores path orientation, and does not support holes. This allows the effect to implement a nonzero fill rule on the shapes. The primary application of this effect is to create stencils from extruded paths so that overlapping sections are not drawn twice (which has negative effects on alpha blending).
CLAMP	Limits drawing so that each pixel is updated once. This effect is a variation of StencilMode#STAMP that also draws as it writes to the stencil buffer. This guarantees that each pixel is updated exactly once. This is used by extruded paths so that overlapping sections are not drawn twice (which has negative effects on alpha blending).
STAMP_EVENODD	Adds a stencil region the buffer This effect will not have any immediate visible effects. Instead it is a variation of StencilMode#STAMP that creates a stencil region for modes such as StencilMode#CLIP, StencilMode#MASK, and the like. The shapes are drawn to the stencil buffer using an even-odd fill rule. It respects orienation and can be used to draw a stencil for a polygon with holes. This has the disadvantage that stamps drawn on top of each other have an "erasing" effect. However, it does not have the polygon limitations that StencilMode#STAMP_NONZERO does.
STAMP_NONZERO	Adds a stencil region the buffer This effect will not have any immediate visible effects. Instead it is a variation of StencilMode#STAMP that creates a stencil region for modes such as StencilMode#CLIP, StencilMode#MASK, and the like. The shapes are drawn to the stencil buffer using a nonzero fill rule. It respects orienation and can be used to draw a stencil for a polygon with holes. This has the advantage that (unlike an even-odd fill rule) stamps are additive and can be drawn on top of each other. However, the size of the stencil buffer means that more than 256 overlapping polygons of the same orientation will cause unpredictable effects.
CLEAR	Erases pixels from the stenciled region. This effect will not draw anything to the screen. Instead, it will only draw to the stencil buffer directly. Any pixel drawn will be zeroed in the buffer, removing it from the stencil region. The modes StencilMode#CLIP_CLEAR and StencilMode#MASK_CLEAR are built upon this idea. However, this mode allows you to clip without drawing anything.

StencilOp

enum class cugl::graphics::StencilOp : int

strong

An enum representing stencil operations.

This enum is an abstraction of constants like GL_KEEP or the Vulkan equivalent VK_STENCIL_OP_KEEP.

Enumerator
KEEP	Keep the current value of the stencil buffer
ZERO	Set the stencil buffer value to 0
REPLACE	Replace the stencil buffer value with the reference value
INCR_CLAMP	Increments the stencil buffer value, clamping to the maximum
DECR_CLAMP	Decrements the stencil buffer value, clamping to the minimum
INVERT	Bitwise inverts the stencil buffer value
INCR_WRAP	Increments the stencil buffer value, wrapping around on overflow
DECR_WRAP	Decrements the stencil buffer value, wrapping around on underflow

TexelFormat

enum class cugl::graphics::TexelFormat

strong

An enum listing the possible texture pixel formats.

This enum defines the texel formats supported by CUGL. As CUGL must support both OpenGLES and Vulkan, it only supports a small subset of formats. CUGL will convert these values into the format for the appropriate platform.

Enumerator
UNDEFINED	An undefined/uninitialized texel format VULKAN ONLY: This format will fail in OpenGL
CUSTOM	A texel format directly defined by the developer VULKAN ONLY: This format will fail in OpenGL
COLOR_RGBA	RGB with alpha transparency, 8 bits per channel This is the default format
COLOR_RGBA4	RGB with alpha transparency, 4 bits per channel
COLOR_BGRA	BGRA (alpha with blue as the highest bit), 8 bits per channel While supported by both OpenGL and Vulkan, some Vulkan implementations specifically need this format.
COLOR_BGRA4	BGRA (alpha with blue as the highest bit), 4 bits per channel
COLOR_RGB	RGB with no alpha, 8 bits per channel
COLOR_RGB4	RGB with no alpha, 4 bits per channel
COLOR_RG	Two color format (red-green) with 8 bits per channel
COLOR_RG4	Two color format (red-green) with 4 bits per channel
COLOR_RED	A monocolor format (red), 8 bits per channel
DEPTH	A depth-only format The data type (for the only attribute) is float. On most platforms this is 32 bit, though some platforms only use 16 bits.
STENCIL	A stencil only format The data type (for the only attribute) is an 8 bit integer.
DEPTH_STENCIL	A combined depth and stencil format This format gives 24 bytes to depth and 8 bits to the stencil.

TextureFilter

enum class cugl::graphics::TextureFilter : int

strong

An enum representing the texture filter options.

This enum is an abstraction of constants like GL_LINEAR or the Vulkan equivalent VK_FILTER_LINEAR. We use the OpenGL naming scheme as it allows us to combine mipmap and texture filter into a single enumeration.

Enumerator
NEAREST	Filtering selects the nearest value
LINEAR	Filtering selects a linearly interpolated value
NEAREST_MIPMAP_NEAREST	Filtering selects the nearest value from the nearest mipmap
LINEAR_MIPMAP_NEAREST	Filtering selects a linearly interpolated value from the nearest mipmap
NEAREST_MIPMAP_LINEAR	Filtering selects the nearest value from a linearly interpolated mipmap
LINEAR_MIPMAP_LINEAR	Filtering selects a linearly interpolated value from a linearly interpolated mipmap

TextureWrap

enum class cugl::graphics::TextureWrap : int

strong

An enum represeting a texture wrap parameter.

This enum is an abstraction of constants like GL_REPEAT or the Vulkan equivalent VK_SAMPLER_ADDRESS_MODE_REPEAT.

Enumerator
CLAMP	Clamps texture values to the edges of the texture
REPEAT	Repeats the texture for values outside of [0,1]
MIRROR	Repeats the texture for values outside of [0,1], reversing at odd values
BORDER	Sets texture values outside of [0,1] to be a constant color

VerticalAlign

enum class cugl::graphics::VerticalAlign

strong

This enumeration represents the vertical alignment of each line of text.

The vertical defines the y-coordinate origin of this text layout. In the case of multiple lines, the alignment is (often) with respect to the entire block of text, not just the first line.

Enumerator
BASELINE	Anchors the block according to the text baseline (DEFAULT) In the case of a multi-line block, the y-origin is the baseline of the first (top) line, assuming that text reads top-to-bottom.
BOTTOM	Anchors the block at the bottom, as defined by the font descent The descent is the amount space below the baseline that the font reserves for its characters. This space will be included even if no character in the block is below the baseline. In the case of a multi-line block, the y-origin is the bottom of the last line.
MIDDLE	Anchors the block at the natural center. This option uses the font height when computing the center. This means including the descent below the bottom line and the ascent above the top line, even if no characters use that space. In the case of a multi-line block, the y-origin is computed as the center of the ascent of the first line to the descent of the last line.
TOP	Anchors the block at the top, as defined by the font ascent The ascent is the amount space above the baseline that the font reserves for its characters. This space will be included even if no character in the block uses the full ascent. In the case of a multi-line block, the y-origin is the top of the first line.
HARD_BOTTOM	Anchors the block at the visible bottom This option ignores the font descent when computing the y-origin. To the y-coordinate origin is placed so that the it touches the character with the greatest extent below the baseline. If no characters are below the baseline, it uses the baseline as the bottom. In the case of a multi-line block, the y-origin is the bottom of the last line.
TRUE_MIDDLE	Anchors the block at the visible middle This option ignores the font height when computing the y-origin. It measures the center from the top of the highest character to the bottom of the character with greatest extent below the baseline. If no characters are below the baseline, it uses the baseline as the bottom. In the case of a multi-line block, the y-origin is centered between the highest character of the first line, and the visible bottom of the last line.
HARD_TOP	Anchors the block at the visible top This option ignores the font ascent when computing the y-origin. To the y-coordinate origin is placed so that the it touches the the top of the highest character above the baseline. In the case of a multi-line block, the y-origin is the top of the first line.

Function Documentation

json_blend_mode()

BlendMode cugl::graphics::json_blend_mode

(

std::string

name

)

Returns the blend mode for the given name

This function converts JSON directory entries into BlendMode values. If the name is invalid, it returns BlendMode#PREMULT.

Parameters

name	The JSON name for the blend mode

Returns

the blend mode for the given name

json_color()

Color4 cugl::graphics::json_color	(	JsonValue *	entry,
		std::string	backup
	)

Returns the color value for the given JSON entry

A color entry is either a four-element integer array (values 0..255) or a string. Any string should be a web color or a Tkinter color name.

Parameters

entry	The JSON entry for the color
backup	Default color to use on failure

Returns

the color value for the given JSON entry

json_filter()

TextureFilter cugl::graphics::json_filter

(

const std::string

name

)

Returns the texture filter for the given name

This function converts JSON directory entries into TextureFilter values. If the name is invalid, it returns TextureFilter#LINEAR.

Parameters

name	The JSON name for the texture filter

Returns

the texture filter for the given name

json_wrap()

TextureWrap cugl::graphics::json_wrap

(

const std::string

name

)

Returns the texture wrap for the given name

This function converts JSON directory entries into TextureWrap values. If the name is invalid, it returns TextureWrap#CLAMP.

Parameters

name	The JSON name for the texture wrap

Returns

the texture wrap for the given name

operator&()

Font::Style cugl::graphics::operator& ( Font::Style  lhs, Font::Style  rhs  )

inline

Returns the bitwise and of two font styles.

Returns

the bitwise and of two font styles.

operator*()

int cugl::graphics::operator* ( Font::Style  value )

inline

Returns the int equivalent of a font style.

Returns

the int equivalent of a font style.

operator^()

Font::Style cugl::graphics::operator^ ( Font::Style  lhs, Font::Style  rhs  )

inline

Returns the bitwise exclusive or of two font styles.

Returns

the bitwise exclusive or of two font styles.

operator|()

Font::Style cugl::graphics::operator| ( Font::Style  lhs, Font::Style  rhs  )

inline

Returns the bitwise or of two font styles.

Returns

the bitwise or of two font styles.

operator~()

Font::Style cugl::graphics::operator~ ( Font::Style  lhs )

inline

Returns the bitwise complement of a font style.

Returns

the bitwise complement of a font style.

parse_mesh()

template<typename T >

void cugl::graphics::parse_mesh	(	Mesh< T > &	mesh,
		const std::shared_ptr< JsonValue > &	json
	)

Populates a the mesh with the date in the given JsonValue.

For this template function to work, the type T must have a constructor that takes a JsonValue to initialize an individual vertex. Note that SpriteVertex has such a constructor.

The mesh can be represented as either an array or JSON object. If it is an array, it then it should contain JSON values compatible with the constructor for that type. If it is a JSON object, then it supports the following attributes:

"vertices":      An array vertex specific descriptions
"indices":       An intenger list of triangle indices (in multiples of 3)
"triangulator":  One of 'monotone', 'earclip', 'delaunay', 'fan', or 'strip'

All attributes are optional. If "vertices" are missing, the mesh will be empty. If both "indices" and "triangulator" are missing, the mesh will use a triangle fan. The "triangulator" choice will only be applied if the "indices" are missing.

Template Parameters

T	The vertex type

Parameters

mesh	The mesh to populate
json	The JSON object specifying the mesh

sdl_flip_vertically()

void cugl::graphics::sdl_flip_vertically

(

SDL_Surface *

surf

)

Flips the pixel data in an SDL surface.

This converts the SDL to OpenGL coordinates, to make it easier to use.

Parameters

surf	The SDL surface