#include <CUGraphicsShader.h>

Inheritance diagram for cugl::graphics::GraphicsShader:

Public Member Functions
	GraphicsShader ()

	~GraphicsShader ()

virtual void	dispose ()

virtual bool	init (const ShaderSource &vsource, const ShaderSource &fsource)

bool	declareAttribute (const std::string name, const AttributeDef &def)

const AttributeDef *	getAttributeDef (const std::string name) const

void	setInstanced (Uint32 group, bool instanced)

void	setAttributeStride (Uint32 group, size_t stride)

bool	declareUniform (const std::string name, const UniformDef &def)

const UniformDef *	getUniformDef (const std::string name) const

bool	declareResource (const std::string name, const ResourceDef &def)

const ResourceDef *	getResourceDef (const std::string name) const

void	setRenderPass (const std::shared_ptr< RenderPass > &pass)

const std::shared_ptr< RenderPass > &	getRenderPass () const

bool	compile ()

bool	isReady () const

void	enableViewScissor (bool enable)

bool	usesViewScissor () const

void	setViewScissor (Uint32 x, Uint32 y, Uint32 w, Uint32 h)

void	setViewScissor (const Rect &scissor)

Rect	getViewScissor ()

void	enableBlending (bool enable)

bool	usesBlending () const

void	enableDepthTest (bool enable)

bool	usesDepthTest () const

void	enableDepthWrite (bool enable)

bool	usesDepthWrite () const

void	enableStencilTest (bool enable)

bool	usesStencilTest () const

void	setDrawMode (DrawMode mode)

DrawMode	getDrawMode () const

void	setFrontFace (FrontFace face)

FrontFace	getFrontFace () const

void	setCullMode (CullMode mode)

CullMode	getCullMode () const

void	setDepthFunc (CompareOp func)

CompareOp	getDepthFunc () const

void	setStencilState (const StencilState &stencil)

void	setFrontStencilState (const StencilState &stencil)

void	setBackStencilState (const StencilState &stencil)

const StencilState &	getFrontStencilState () const

const StencilState &	getBackStencilState () const

void	setColorMask (Uint8 mask)

Uint8	getColorMask () const

void	setStencilMode (StencilMode mode)

void	setBlendState (const BlendState &blend)

const BlendState &	getBlendState () const

void	setBlendMode (BlendMode mode)

void	setLineWidth (float width)

float	getLineWidth () const

void	setVertices (Uint32 group, const std::shared_ptr< VertexBuffer > &vertices)

const std::shared_ptr< VertexBuffer >	getVertices (Uint32 group) const

void	setIndices (const std::shared_ptr< IndexBuffer > &indices)

const std::shared_ptr< IndexBuffer >	getIndices () const

void	setUniformBuffer (const std::string name, const std::shared_ptr< UniformBuffer > &buffer)

void	setUniformBuffers (const std::string name, const std::vector< std::shared_ptr< UniformBuffer > > &buffers)

const std::shared_ptr< UniformBuffer >	getUniformBuffer (const std::string name) const

const std::vector< std::shared_ptr< UniformBuffer > >	getUniformBuffers (const std::string name) const

void	setStorageBuffer (const std::string name, const std::shared_ptr< StorageBuffer > &buffer)

void	setStorageBuffers (const std::string name, const std::vector< std::shared_ptr< StorageBuffer > > &buffers)

const std::shared_ptr< StorageBuffer >	getStorageBuffer (const std::string name) const

const std::vector< std::shared_ptr< StorageBuffer > >	getStorageBuffers (const std::string name) const

void	setBlock (const std::string name, Uint32 block)

Uint32	getBlock (const std::string name)

void	setTexture (const std::string name, const std::shared_ptr< Texture > &texture)

void	setTextures (const std::string name, const std::vector< std::shared_ptr< Texture > > &textures)

const std::shared_ptr< Texture >	getTexture (const std::string name) const

const std::vector< std::shared_ptr< Texture > >	getTextures (const std::string name) const

void	setTextureArray (const std::string name, const std::shared_ptr< TextureArray > &array)

void	setTextureArrays (const std::string name, const std::vector< std::shared_ptr< TextureArray > > &arrays)

const std::shared_ptr< TextureArray >	getTextureArray (const std::string name) const

const std::vector< std::shared_ptr< TextureArray > >	getTextureArrays (const std::string name) const

void	setImage (const std::string name, const std::shared_ptr< Image > &image)

void	setImages (const std::string name, const std::vector< std::shared_ptr< Image > > &images)

const std::shared_ptr< Image >	getImage (const std::string name) const

const std::vector< std::shared_ptr< Image > >	getImages (const std::string name) const

void	setImageArray (const std::string name, const std::shared_ptr< ImageArray > &array)

void	setImageArrays (const std::string name, const std::vector< std::shared_ptr< ImageArray > > &arrays)

const std::shared_ptr< ImageArray >	getImageArray (const std::string name) const

const std::vector< std::shared_ptr< ImageArray > >	getImageArrays (const std::string name) const

void	setSampler (const std::string name, const std::shared_ptr< Sampler > &sampler)

void	setSamplers (const std::string name, const std::vector< std::shared_ptr< Sampler > > &samplers)

const std::shared_ptr< Sampler >	getSampler (const std::string name) const

const std::vector< std::shared_ptr< Sampler > >	getSamplers (const std::string name) const

void	pushInt (const std::string name, Sint32 value)

void	pushUInt (const std::string name, Uint32 value)

void	pushFloat (const std::string name, float value)

void	pushVec2 (const std::string name, const Vec2 &vec)

void	pushVec2 (const std::string name, float x, float y)

void	pushVec3 (const std::string name, const Vec3 &vec)

void	pushVec3 (const std::string name, float x, float y, float z)

void	pushVec4 (const std::string name, const Vec4 &vec)

void	pushVec4 (const std::string name, const Quaternion &quat)

void	pushVec4 (const std::string name, float x, float y, float z, float w)

void	pushIVec2 (const std::string name, Sint32 x, Sint32 y)

void	pushIVec3 (const std::string name, Sint32 x, Sint32 y, Sint32 z)

void	pushIVec4 (const std::string name, Sint32 x, Sint32 y, Sint32 z, Sint32 w)

void	pushUVec2 (const std::string name, Uint32 x, Uint32 y)

void	pushUVec3 (const std::string name, Uint32 x, Uint32 y, Uint32 z)

void	pushUVec4 (const std::string name, Uint32 x, Uint32 y, Uint32 z, Uint32 w)

void	pushColor4f (const std::string name, const Color4f &color)

void	pushColor4f (const std::string name, float red, float green, float blue, float alpha)

void	pushColor4 (const std::string name, const Color4 color)

void	pushColor4 (const std::string name, Uint8 red, Uint8 green, Uint8 blue, Uint8 alpha)

void	pushMat2 (const std::string name, const Affine2 &mat)

void	pushMat2 (const std::string name, const float *array)

void	pushMat3 (const std::string name, const Affine2 &mat)

void	pushMat3 (const std::string name, const float *array)

void	pushMat4 (const std::string name, const Mat4 &mat)

void	pushMat4 (const std::string name, const float *array)

void	push (const std::string name, Uint8 *data)

template<typename T >
void	push (const std::string name, T value)

void	begin ()

void	begin (const std::shared_ptr< FrameBuffer > &framebuffer)

void	end ()

void	draw (Uint32 count, Uint32 offset=0)

void	drawIndexed (Uint32 count, Uint32 offset=0)

void	drawInstances (Uint32 count, Uint32 instances, Uint32 vtxoff=0, Uint32 insoff=0)

void	drawInstancesIndexed (Uint32 count, Uint32 instances, Uint32 idxoff=0, Uint32 insoff=0)

Static Public Member Functions
static std::shared_ptr< GraphicsShader >	alloc (const ShaderSource &vsource, ShaderSource &fsource)

Protected Member Functions
bool	validate ()

bool	isCompatible (const std::shared_ptr< FrameBuffer > &framebuffer)

void	flush ()

Protected Attributes
GraphicsShaderData *	_data

ShaderSource	_vertModule

ShaderSource	_fragModule

size_t	_attachments

std::unordered_map< std::string, AttributeDef >	_attributes

std::vector< Uint32 >	_attrStride

std::unordered_map< std::string, UniformDef >	_uniforms

std::unordered_map< std::string, ResourceDef >	_resources

std::unordered_set< Uint32 >	_instances

Uint32	_initialGroup

std::vector< std::shared_ptr< VertexBuffer > >	_vertices

std::shared_ptr< IndexBuffer >	_indices

std::unordered_map< std::string, ResourceData * >	_values

std::shared_ptr< RenderPass >	_renderpass

std::shared_ptr< FrameBuffer >	_framebuffer

Static Protected Attributes
static std::shared_ptr< GraphicsShader >	g_shader

Detailed Description

This class defines a GLSL shader.

This class compiles and links any well-defined GLSL shader. It also has methods for querying and binding the shader. The class is written to be agnostic about whether we are using OpenGL, OpenGLES, or Vulkan. It is reasonably lightweight enough to be general purpose. However, it only supports basic vertex buffers and 2d textures. If you need anything more than this, you may need to create your own shader class (which will be specific to your platform). For example, if you wish to separate textures from their samplers,

Because of difference in how OpenGL and Vulkan define uniforms, we actually have two types of uniforms. Uniforms refer to values that are changed directly in the shader without any intermediate data structure; in Vulkan these are referred to as push constants. Resource, on the other hand, include uniforms that require additional data structures, such as textures, texture arrays, and uniform buffers. While OpenGL allows for an unlimited number of uniforms without the use of uniform buffers, Vulkan typically only allows 192 bytes for push constants (generally enough to set the camera), and all other uniforms must be handled by uniform buffers.

Because of the limitations of OpenGLES, this class only supports vertex and fragment shaders. It does not support tesselation or geometry shaders. Furthermore, keep in mind that Apple has deprecated OpenGL. MacOS devices are stuck at OpenGL 4.1 and iOS devices are stuck at OpenGLES 3.1. So it is not safe to use any shader more recent than version 330 on any platform.

In addition, this shader does not support indirect drawing. This is due to a limitation of MoltenVK, where indirect draws are always converted into a an explicit CPU loop anyway.

Constructor & Destructor Documentation

◆ GraphicsShader()

cugl::graphics::GraphicsShader::GraphicsShader ( )

inline

Creates an uninitialized shader with no source.

You must initialize the shader to add a source and compile it.

◆ ~GraphicsShader()

cugl::graphics::GraphicsShader::~GraphicsShader ( )

inline

Deletes this shader, disposing all resources.

Member Function Documentation

◆ alloc()

static std::shared_ptr< GraphicsShader > cugl::graphics::GraphicsShader::alloc	(	const ShaderSource &	vsource,
		ShaderSource &	fsource
	)

inlinestatic

Returns a new shader with the given vertex and fragment source.

This method will allocate resources for a shader, but it will not compile it. You must all the compile method to compile the shader.

Parameters

vsource	The source for the vertex shader.
fsource	The source for the fragment shader.

Returns: a new shader with the given vertex and fragment source.

◆ begin() [1/2]

void cugl::graphics::GraphicsShader::begin ( )

Begins a render pass with this shader for the application display.

Once this method is called, no other graphics shader can begin a render pass. You must complete this render pass with end before starting a new pass.

This method will fail if getRenderPass is not compatible with RenderPass::getDisplay().

◆ begin() [2/2]

void cugl::graphics::GraphicsShader::begin ( const std::shared_ptr< FrameBuffer > & framebuffer )

Begins a render pass with this shader for the given framebuffer

Once this method is called, no other graphics shader can begin a render pass. You must complete this render pass with end before starting a new pass.

This method will fail if getRenderPass does not agree with that of the framebuffer

Parameters

framebuffer The framebuffer to target this pass

◆ compile()

bool cugl::graphics::GraphicsShader::compile ( )

Compiles this shader for use

All variables (attributes, uniforms, and resources) should be declared before compilation. If the shader is designed for a non-traditional renderpass with multiple framebuffers, that should be set as well. Once compilation is successful, this shader should be ready for use.

If compilation fails, it will display error messages on the log.

Returns: true if compilation was successful.

◆ declareAttribute()

bool cugl::graphics::GraphicsShader::declareAttribute	(	const std::string	name,
		const AttributeDef &	def
	)

Declares a shader attribute.

In order to be used, each attribute must be declared before the graphics shader is compiled via compile. The declaration links a name to an attribute variables not declared cannot be accesses, and in some cases (e.g. Vulkan) prevent the attribute from being accessed.

This method can fail if the attribute has already been declared.

Parameters

name	The attribute name
def	The attribute type, size, and location

Returns: true if the declaration was successful

◆ declareResource()

bool cugl::graphics::GraphicsShader::declareResource	(	const std::string	name,
		const ResourceDef &	def
	)

Declares a shader resource uniform.

Resource uniforms include uniform buffers and textures. In order to be used, each resource must be declared before the graphics shader is compiled via compile. The declaration links a name to a resource definition. We can use this name to load data via methods such as setUniformBuffer and setTexture.

Note that resource arrays are only permitted in Vulkan. In OpenGL, each resource is a single object.

This method can fail if the resource has already been declared.

Parameters

name	The descriptor name
def	The descriptor type, size, and location

Returns: true if the declaration was successful

◆ declareUniform()

bool cugl::graphics::GraphicsShader::declareUniform	(	const std::string	name,
		const UniformDef &	def
	)

Declares a shader push-constant uniform.

In order to be used, each push-constant must be declared before the graphics shader is compiled via compile. The declaration links a name to a uniform definition. We can use this name to push data to the graphics shader via an of the push methods.

Note that in OpenGL, a push constant is just any uniform that is not associated with a uniform buffer (e.g. a traditional uniform).

This method can fail if the uniform has already been declared.

Parameters

name	The uniform name
def	The uniform type, size, and location

Returns: true if the declaration was successful

◆ dispose()

virtual void cugl::graphics::GraphicsShader::dispose ( )

virtual

Deletes the shader and resets all attributes.

You must reinitialize the shader to use it.

Reimplemented in cugl::graphics::ParticleShader, cugl::scene3::BillboardShader, and cugl::scene3::ObjShader.

◆ draw()

void cugl::graphics::GraphicsShader::draw	(	Uint32	count,
		Uint32	offset = `0`
	)

Draws to the active render pass

This draw command will ignore the index buffer and draw the vertices in the order that they were loaded. Any call to this command will use the current texture and uniforms, as well as the drawing topology set by setDrawMode. If any of these values need to be changed, then this draw command will need to be broken up into chunks. Use the vertex offset parameter to chunk up draw calls without having to reload data.

Note that any attribute group that is instanced will only be accessed once, no matter how many vertices are drawn.

This method will only succeed if this shader is in the middle of a render pass.

Parameters

count	The number of vertices to draw
offset	The vertex offset to start with

◆ drawIndexed()

void cugl::graphics::GraphicsShader::drawIndexed	(	Uint32	count,
		Uint32	offset = `0`
	)

Draws to the active render pass

This draw command will use the index buffer to stream the vertices in order. Any call to this command will use the current texture and uniforms, as well as the drawing topology set by setDrawMode. If any of these values need to be changed, then this draw command will need to be broken up into chunks. Use the index offset parameter to chunk up draw calls without having to reload data.

Note that any attribute group that is instanced will only be accessed once, no matter how many vertices are drawn.

This method will only succeed if this shader is in the middle of a render pass.

Parameters

count	The number of vertices to draw
offset	The initial index to start with

◆ drawInstances()

void cugl::graphics::GraphicsShader::drawInstances	(	Uint32	count,
		Uint32	instances,
		Uint32	vtxoff = `0`,
		Uint32	insoff = `0`
	)

Draws to the active render pass for the given number of instances

This draw command will create a mesh of count vertices from the non-instanced attributes. Like draw, this mesh will ignore the index buffer and take the vertices in he order that they were loaded. It will then repeat this mesh instance number of times using the data in the instanced attributes. The instance data will be taken from the instanced attribute groups, starting at position insoff.

Any call to this command will use the current texture and uniforms, as well as the drawing topology set by setDrawMode. If any of these values need to be changed, then this draw command will need to be broken up into chunks. Use the vertex offset parameter to chunk up draw calls without having to reload data.

This method will only succeed if this shader is in the middle of a render pass.

Parameters

count	The number of vertices in the base mesh
instances	The number of mesh instances
vtxoff	The offset of the initial vertex in the base mesh
insoff	The offset in the instance data

◆ drawInstancesIndexed()

void cugl::graphics::GraphicsShader::drawInstancesIndexed	(	Uint32	count,
		Uint32	instances,
		Uint32	idxoff = `0`,
		Uint32	insoff = `0`
	)

Draws to the active render pass for the given number of instances

This draw command will create a mesh of count vertices from the non-instanced attributes. Like drawIndexed, this mesh will use the index buffer to define its vertices. It will then repeat this mesh instance number of times using the data in the instanced attributes. The instance data will be taken from the instanced attribute groups, starting at position insoff.

Any call to this command will use the current texture and uniforms, as well as the drawing topology set by setDrawMode. If any of these values need to be changed, then this draw command will need to be broken up into chunks. Use the vertex offset parameter to chunk up draw calls without having to reload data.

This method will only succeed if this shader is in the middle of a render pass.

Parameters

count	The number of vertices in the base mesh
instances	The number of mesh instances
idxoff	The offset of the initial index in the base mesh
insoff	The offset in the instance data

◆ enableBlending()

void cugl::graphics::GraphicsShader::enableBlending ( bool enable )

Sets whether color blending is enabled.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

enable Whether to enable color blendings

◆ enableDepthTest()

void cugl::graphics::GraphicsShader::enableDepthTest ( bool enable )

Sets whether depth testing is enabled.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

enable Whether to enable depth testing

◆ enableDepthWrite()

void cugl::graphics::GraphicsShader::enableDepthWrite ( bool enable )

Sets whether depth writing is enabled.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

enable Whether to enable depth writing

◆ enableStencilTest()

void cugl::graphics::GraphicsShader::enableStencilTest ( bool enable )

Sets whether stencil testing is enabled.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

enable Whether to enable stencil testing

◆ enableViewScissor()

void cugl::graphics::GraphicsShader::enableViewScissor ( bool enable )

Sets whether the view scissor is enabled in this graphics shader.

This is a drawing primitive that is distinct from the Scissor class. That is a rotational scissor supported by SpriteBatch.

Changing this value has no immediate effect if it is called in the middle of a render pass. Instead, it will be applies at the next call to begin.

Parameters

enable Whether to enable the view scissor

◆ end()

void cugl::graphics::GraphicsShader::end ( )

Ends the render pass for this shader.

Once this method is called, it is safe to start a render pass with another shader. This method has no effect if there is no active render pass for this shader.

◆ flush()

void cugl::graphics::GraphicsShader::flush ( )

protected

Updates all descriptors and buffers before drawing.

◆ getAttributeDef()

const AttributeDef * cugl::graphics::GraphicsShader::getAttributeDef ( const std::string name ) const

Returns the attribute definition for the given variable name.

If there is no attribute definition for the given name, this method returns nullptr.

Parameters

name	The attribute name

Returns: the attribute definition for the given variable name.

◆ getBackStencilState()

const StencilState & cugl::graphics::GraphicsShader::getBackStencilState ( ) const

Returns the back-facing stencil state for this graphics shader

This setting will only apply to triangles that are back-facing. Use getFrontStencilState to see the setting for front-facing triangles.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Returns: the back-facing stencil state for this graphics shader

◆ getBlendState()

const BlendState & cugl::graphics::GraphicsShader::getBlendState ( ) const

Returns the color blend state for this graphics shader

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Returns: the color blend state for this graphics shader

◆ getBlock()

Uint32 cugl::graphics::GraphicsShader::getBlock ( const std::string name )

Returns the active block of the associated resource buffer

If the type of the resource is not ResourceType#MULTI_BUFFER or ResourceType#MULTI_STORAGE, this method return 0. This block will be used in the next draw call.

Parameters

name	The name of the resource

Returns: the uniform block for the given resource variable

◆ getColorMask()

Uint8 cugl::graphics::GraphicsShader::getColorMask ( ) const

Returns the color mask for stencils in this graphics shader

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Returns: the color mask for stencils in this graphics shader

◆ getCullMode()

CullMode cugl::graphics::GraphicsShader::getCullMode ( ) const

Returns the active triangle culling mode for this shader

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Returns: the active triangle culling mode for this shader

◆ getDepthFunc()

CompareOp cugl::graphics::GraphicsShader::getDepthFunc ( ) const

Returns the depth comparions function for this graphics shader

If depth testing is enabled, the graphics shader will discard any fragments that fail this comparison.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Returns: the depth comparions function for this graphics shader

◆ getDrawMode()

DrawMode cugl::graphics::GraphicsShader::getDrawMode ( ) const

Returns the active draw mode of this shader.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Returns: the active draw mode of this shader.

◆ getFrontFace()

FrontFace cugl::graphics::GraphicsShader::getFrontFace ( ) const

Returns the active front-facing orientation for triangles

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Returns: the active front-facing orientation for triangles

◆ getFrontStencilState()

const StencilState & cugl::graphics::GraphicsShader::getFrontStencilState ( ) const

Returns the font-facing stencil state for this graphics shader

This setting will only apply to triangles that are front-facing. Use getBackStencilState to see the setting for back-facing triangles.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Returns: the font-facing stencil state for this graphics shader

◆ getImage()

const std::shared_ptr< Image > cugl::graphics::GraphicsShader::getImage ( const std::string name ) const

Returns the image for the given resource variable

VULKAN ONLY: If the variable does not refer to an image (a texture2D in GLSL), then this method will return nullptr. If more than one image is assigned to this attribute, then this method will return the first one.

Any image assigned to a name is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource

Returns: the image for the given resource variable

◆ getImageArray()

const std::shared_ptr< ImageArray > cugl::graphics::GraphicsShader::getImageArray ( const std::string name ) const

Returns the image array for the given resource variable

VULKAN ONLY: If the variable does not refer to an image array (a texture2DArray in GLSL), then this method will return nullptr. If more than one image array is assigned to this attribute, then this method will return the first one.

Any image array assigned to a name is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource

Returns: the image array for the given resource variable

◆ getImageArrays()

const std::vector< std::shared_ptr< ImageArray > > cugl::graphics::GraphicsShader::getImageArrays ( const std::string name ) const

Returns the image arrays for the given resource variable

VULKAN ONLY: If the variable does not refer to an image array (a texture2DArray in GLSL), then this method will return an empty vector.

Any image arrays assigned to a name are stateful, in that they will persist across render passes.

Parameters

name	The name of the resource

Returns: the image arrays for the given resource variable

◆ getImages()

const std::vector< std::shared_ptr< Image > > cugl::graphics::GraphicsShader::getImages ( const std::string name ) const

Returns the images for the given resource variable

VULKAN ONLY: If the variable does not refer to an image (a texture2D in GLSL), then this method will return an empty vector.

Any images assigned to a name are stateful, in that they will persist across render passes.

Parameters

name	The name of the resource

Returns: the images for the given resource variable

◆ getIndices()

const std::shared_ptr< IndexBuffer > cugl::graphics::GraphicsShader::getIndices ( ) const

Returns the indices assigned to the shader

These indices define the drawing topology and are applied to all attached vertex buffers that are not members of an instanced group. They define the behavior of the methods drawIndexed and drawInstancesIndexed.

Returns: the indices assigned to the shader

◆ getLineWidth()

float cugl::graphics::GraphicsShader::getLineWidth ( ) const

Returns the line width for this graphics shader

VULKAN ONLY: This feature is not supported in OpenGL. In Vulkan this defines the pixel width of a line.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Returns: the line width for this graphics shader

◆ getRenderPass()

const std::shared_ptr< RenderPass > & cugl::graphics::GraphicsShader::getRenderPass ( ) const

inline

Returns the default render pass for this shader

The render pass determines what FrameBuffer objects can be used with this graphics shader. The RenderPass of the framebuffer must be compatible with this renderpass as determined by RenderPass#isCompatible.

If this value is not set, or is nullptr, then graphics shader is compiled to be used with the display. It can still be used with any compatible FrameBuffer, which is any framebuffer with one color attachment and a depth buffer.

Returns: the default render pass for this shader

◆ getResourceDef()

const ResourceDef * cugl::graphics::GraphicsShader::getResourceDef ( const std::string name ) const

Returns the resource definition for the given variable name.

If there is no resource definition for the given name, this method returns nullptr.

Parameters

name	The attribute name

Returns: the resource definition for the given variable name.

◆ getSampler()

const std::shared_ptr< Sampler > cugl::graphics::GraphicsShader::getSampler ( const std::string name ) const

Returns the sampler for the given resource variable

VULKAN ONLY: If the variable does not refer to a sampler (a sampler in GLSL), then this method will return nullptr. If more than one sampler is assigned to this attribute, then this method will return the first one.

Any sampler assigned to a name is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource

Returns: the sampler for the given resource variable

◆ getSamplers()

const std::vector< std::shared_ptr< Sampler > > cugl::graphics::GraphicsShader::getSamplers ( const std::string name ) const

Returns the samplers for the given resource variable

VULKAN ONLY: If the variable does not refer to a sampler (a sampler in GLSL), then this method will return an empty vector.

Any samplers assigned to a name are stateful, in that they will persist across render passes.

Parameters

name	The name of the resource

Returns: the samplers for the given resource variable

◆ getStorageBuffer()

const std::shared_ptr< StorageBuffer > cugl::graphics::GraphicsShader::getStorageBuffer ( const std::string name ) const

Returns the storage buffer for the given resource variable

VULKAN ONLY: If the variable does not refer to a storage buffer, then this method will return nullptr. If more than one buffer is assigned to this attribute, then this method will return the first one.

Any buffer assigned to a name is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource

Returns: the storage buffer for the given resource variable

◆ getStorageBuffers()

const std::vector< std::shared_ptr< StorageBuffer > > cugl::graphics::GraphicsShader::getStorageBuffers ( const std::string name ) const

Returns the storage buffers for the given resource variable

VULKAN ONLY: If the variable does not refer to a storage buffer, then this method will return an empty vector.

Any buffer assigned to a name is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource

Returns: the storage buffers for the given resource variable

◆ getTexture()

const std::shared_ptr< Texture > cugl::graphics::GraphicsShader::getTexture ( const std::string name ) const

Returns the texture for the given resource variable

If the variable does not refer to a texture (a sampler2d in GLSL), then this method will return nullptr. If more than one texture is assigned to this attribute, then this method will return the first one.

Any texture assigned to a name is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource

Returns: the texture for the given resource variable

◆ getTextureArray()

const std::shared_ptr< TextureArray > cugl::graphics::GraphicsShader::getTextureArray ( const std::string name ) const

Returns the texture array for the given resource variable

If the variable does not refer to a texture array (a sampler2DArray in GLSL), then this method will return nullptr. If more than one texture array is assigned to this attribute, then this method will return the first one.

Any texture array assigned to a name is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource

Returns: the texture array for the given resource variable

◆ getTextureArrays()

const std::vector< std::shared_ptr< TextureArray > > cugl::graphics::GraphicsShader::getTextureArrays ( const std::string name ) const

Returns the texture arrays for the given resource variable

If the variable does not refer to a texture array (a sampler2DArray in GLSL), then this method will return an empty vector.

Any texture arrays assigned to a name are stateful, in that they will persist across render passes.

Parameters

name	The name of the resource

Returns: the texture arrays for the given resource variable

◆ getTextures()

const std::vector< std::shared_ptr< Texture > > cugl::graphics::GraphicsShader::getTextures ( const std::string name ) const

Returns the textures for the given resource variable

If the variable does not refer to a texture (a sampler2D in GLSL), then this method will return an empty vector.

Any textures assigned to a name are stateful, in that they will persist across render passes.

Parameters

name	The name of the resource

Returns: the textures for the given resource variable

◆ getUniformBuffer()

const std::shared_ptr< UniformBuffer > cugl::graphics::GraphicsShader::getUniformBuffer ( const std::string name ) const

Returns the uniform buffer for the given resource variable

If the variable does not refer to a uniform buffer (e.g. a std140 buffer in OpenGL, or a uniform in Vulkan), then this method will return nullptr. If more than one buffer is assigned to this attribute, then this method will return the first one.

Any buffer assigned to a name is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource

Returns: the uniform buffer for the given resource variable

◆ getUniformBuffers()

const std::vector< std::shared_ptr< UniformBuffer > > cugl::graphics::GraphicsShader::getUniformBuffers ( const std::string name ) const

Returns the uniform buffers for the given resource variable

If the variable does not refer to a uniform buffer (e.g. a std140 buffer in OpenGL, or a uniform in Vulkan), then this method will return an empty vector.

Any buffer assigned to a name is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource

Returns: the uniform buffers for the given resource variable

◆ getUniformDef()

const UniformDef * cugl::graphics::GraphicsShader::getUniformDef ( const std::string name ) const

Returns the uniform definition for the given variable name.

If there is no uniform definition for the given name, this method returns nullptr.

Parameters

name	The attribute name

Returns: the uniform definition for the given variable name.

◆ getVertices()

const std::shared_ptr< VertexBuffer > cugl::graphics::GraphicsShader::getVertices ( Uint32 group ) const

Returns the vertex buffer for an attribute group

Attribute groups must be defined in the AttributeDef provided at compile time. All attributes in the vertex buffer must share the same binding group.

Elements in the vertex buffer correspond to vertices. If the attribute group is instanced, these vertices will be indexed by the drawing instance. Otherwise, they will be indexed by the IndexBuffer.

Parameters

group The attribute group

Returns: the vertex buffer for an attribute group

◆ getViewScissor()

Rect cugl::graphics::GraphicsShader::getViewScissor ( )

Returns the AABB scissor value of this graphics shader

This is a drawing primitive that is distinct from the Scissor class. That is a rotational scissor supported by SpriteBatch.

Changing this value has no immediate effect if it is called in the middle of a render pass. Instead, it will be applies at the next call to begin.

Returns: the scissor value of this graphics shader

◆ init()

virtual bool cugl::graphics::GraphicsShader::init	(	const ShaderSource &	vsource,
		const ShaderSource &	fsource
	)

virtual

Initializes this shader with the given vertex and fragment source.

This method will allocate resources for a shader, but it will not compile it. You must all the compile method to compile the shader.

Parameters

vsource	The source for the vertex shader.
fsource	The source for the fragment shader.

Returns: true if initialization was successful.

Reimplemented in cugl::scene3::BillboardShader, cugl::scene3::ObjShader, and cugl::graphics::ParticleShader.

◆ isCompatible()

bool cugl::graphics::GraphicsShader::isCompatible ( const std::shared_ptr< FrameBuffer > & framebuffer )

protected

Returns true if this framebuffer is compatible with this shader

While our graphics shaders do have the ability to dynamically change render passes, they still need to be compatible. In particular, the number of color attachments must match.

Parameters

framebuffer The framebuffer to check

Returns: true if this framebuffer is compatible with this shader

◆ isReady()

bool cugl::graphics::GraphicsShader::isReady ( ) const

Returns true if this shader has been compiled and is ready for use.

Returns: true if this shader has been compiled and is ready for use.

◆ push() [1/2]

template<typename T >

void cugl::graphics::GraphicsShader::push	(	const std::string	name,
		T	value
	)

inline

Sets the given uniform to the provided value.

The data type should match up with the size of the uniform previously declared. If not, the results of this method are undefined.

Note that this method does nothing if it is not invoked during an active begin/end pair. This method does not cache uniforms for later.

Parameters

name	The uniform name
value	The uniform value

◆ push() [2/2]

void cugl::graphics::GraphicsShader::push	(	const std::string	name,
		Uint8 *	data
	)

Sets the given uniform to the provided array.

The array data should have the size of the uniform previously declared. If not, the results of this method are undefined.

Note that this method does nothing if it is not invoked during an active begin/end pair. This method does not cache uniforms for later.

Parameters

name	The uniform name
data	The uniform data

◆ pushColor4() [1/2]

void cugl::graphics::GraphicsShader::pushColor4	(	const std::string	name,
		const Color4	color
	)

Sets the given uniform to a color value.

This will fail if the uniform is not a GLSL ucolor variable.

Parameters

name	The name of the uniform
color	The value for the uniform

◆ pushColor4() [2/2]

void cugl::graphics::GraphicsShader::pushColor4	(	const std::string	name,
		Uint8	red,
		Uint8	green,
		Uint8	blue,
		Uint8	alpha
	)

Sets the given uniform to a color value.

This will fail if the uniform is not a GLSL ucolor variable.

Parameters

name	The name of the uniform
red	The uniform red value
green	The uniform green value
blue	The uniform blue value
alpha	The uniform alpha value

◆ pushColor4f() [1/2]

void cugl::graphics::GraphicsShader::pushColor4f	(	const std::string	name,
		const Color4f &	color
	)

Sets the given uniform to a color value.

This will fail if the uniform is not a GLSL color variable.

Parameters

name	The name of the uniform
color	The value for the uniform

◆ pushColor4f() [2/2]

void cugl::graphics::GraphicsShader::pushColor4f	(	const std::string	name,
		float	red,
		float	green,
		float	blue,
		float	alpha
	)

Sets the given uniform to a color value.

This will fail if the uniform is not a GLSL color variable.

Parameters

name	The name of the uniform
red	The uniform red value
green	The uniform green value
blue	The uniform blue value
alpha	The uniform alpha value

◆ pushFloat()

void cugl::graphics::GraphicsShader::pushFloat	(	const std::string	name,
		float	value
	)

Sets the given uniform to a float value.

This will fail if the uniform is not a GLSL float variable.

Parameters

name	The name of the uniform
value	The value for the uniform

◆ pushInt()

void cugl::graphics::GraphicsShader::pushInt	(	const std::string	name,
		Sint32	value
	)

Sets the given uniform to a integer value.

This will fail if the uniform is not a GLSL int variable.

Note that uniforms can only be pushed during an active begin/end pair. This method does not cache uniforms for later.

Parameters

name	The name of the uniform
value	The value for the uniform

◆ pushIVec2()

void cugl::graphics::GraphicsShader::pushIVec2	(	const std::string	name,
		Sint32	x,
		Sint32	y
	)

Sets the given uniform to the given values

This will fail if the uniform is not a GLSL ivec2 variable.

Parameters

name	The name of the uniform
x	The x-value for the vector
y	The x-value for the vector

◆ pushIVec3()

void cugl::graphics::GraphicsShader::pushIVec3	(	const std::string	name,
		Sint32	x,
		Sint32	y,
		Sint32	z
	)

Sets the given uniform to the given values

This will fail if the uniform is not a GLSL ivec3 variable.

Parameters

name	The name of the uniform
x	The x-value for the vector
y	The x-value for the vector
z	The z-value for the vector

◆ pushIVec4()

void cugl::graphics::GraphicsShader::pushIVec4	(	const std::string	name,
		Sint32	x,
		Sint32	y,
		Sint32	z,
		Sint32	w
	)

Sets the given uniform to the given values

This will fail if the uniform is not a GLSL ivec4 variable.

Parameters

name	The name of the uniform
x	The x-value for the vector
y	The x-value for the vector
z	The z-value for the vector
w	The z-value for the vector

◆ pushMat2() [1/2]

void cugl::graphics::GraphicsShader::pushMat2	(	const std::string	name,
		const Affine2 &	mat
	)

Sets the given uniform to a 2x2 matrix.

The 2x2 matrix will be the non-translational part of the affine transform. This method will fail if the uniform is not a GLSL mat2 variable.

Parameters

name	The name of the uniform
mat	The value for the uniform

◆ pushMat2() [2/2]

void cugl::graphics::GraphicsShader::pushMat2	(	const std::string	name,
		const float *	array
	)

Sets the given uniform to a 2x2 matrix.

The matrix will be read from the array in column major order (not row major). This method will fail if the uniform is not a GLSL mat2 variable.

Parameters

name	The name of the uniform
array	The values for the uniform

◆ pushMat3() [1/2]

void cugl::graphics::GraphicsShader::pushMat3	(	const std::string	name,
		const Affine2 &	mat
	)

Sets the given uniform to a 3x3 matrix.

The 3x3 matrix will be affine transform in homoegenous coordinates. This method will fail if the uniform is not a GLSL mat3 variable.

Parameters

name	The name of the uniform
mat	The value for the uniform

◆ pushMat3() [2/2]

void cugl::graphics::GraphicsShader::pushMat3	(	const std::string	name,
		const float *	array
	)

Sets the given uniform to a 3x3 matrix.

The matrix will be read from the array in column major order (not row major). This method will fail if the uniform is not a GLSL mat3 variable.

Parameters

name	The name of the uniform
array	The values for the uniform

◆ pushMat4() [1/2]

void cugl::graphics::GraphicsShader::pushMat4	(	const std::string	name,
		const float *	array
	)

Sets the given uniform to a 4x4 matrix.

The matrix will be read from the array in column major order (not row major). This method will fail if the uniform is not a GLSL mat4 variable.

Parameters

name	The name of the uniform
array	The values for the uniform

◆ pushMat4() [2/2]

void cugl::graphics::GraphicsShader::pushMat4	(	const std::string	name,
		const Mat4 &	mat
	)

Sets the given uniform to a 4x4 matrix

This will fail if the uniform is not a GLSL mat4 variable.

Parameters

name	The name of the uniform
mat	The value for the uniform

◆ pushUInt()

void cugl::graphics::GraphicsShader::pushUInt	(	const std::string	name,
		Uint32	value
	)

Sets the given uniform to an unsigned integer value.

This will fail if the uniform is not a GLSL uint variable.

Parameters

name	The name of the uniform
value	The value for the uniform

◆ pushUVec2()

void cugl::graphics::GraphicsShader::pushUVec2	(	const std::string	name,
		Uint32	x,
		Uint32	y
	)

Sets the given uniform to the given values

This will fail if the uniform is not a GLSL ivec2 variable.

Parameters

name	The name of the uniform
x	The x-value for the vector
y	The x-value for the vector

◆ pushUVec3()

void cugl::graphics::GraphicsShader::pushUVec3	(	const std::string	name,
		Uint32	x,
		Uint32	y,
		Uint32	z
	)

Sets the given uniform to the given values

This will fail if the uniform is not a GLSL ivec3 variable.

Parameters

name	The name of the uniform
x	The x-value for the vector
y	The x-value for the vector
z	The z-value for the vector

◆ pushUVec4()

void cugl::graphics::GraphicsShader::pushUVec4	(	const std::string	name,
		Uint32	x,
		Uint32	y,
		Uint32	z,
		Uint32	w
	)

Sets the given uniform to the given values

This will fail if the uniform is not a GLSL ivec4 variable.

Parameters

name	The name of the uniform
x	The x-value for the vector
y	The x-value for the vector
z	The z-value for the vector
w	The z-value for the vector

◆ pushVec2() [1/2]

void cugl::graphics::GraphicsShader::pushVec2	(	const std::string	name,
		const Vec2 &	vec
	)

Sets the given uniform to a Vector2 value.

This will fail if the uniform is not a GLSL vec2 variable.

Parameters

name	The name of the uniform
vec	The value for the uniform

◆ pushVec2() [2/2]

void cugl::graphics::GraphicsShader::pushVec2	(	const std::string	name,
		float	x,
		float	y
	)

Sets the given uniform to the given values

This will fail if the uniform is not a GLSL vec2 variable.

Parameters

name	The name of the uniform
x	The x-value for the vector
y	The x-value for the vector

◆ pushVec3() [1/2]

void cugl::graphics::GraphicsShader::pushVec3	(	const std::string	name,
		const Vec3 &	vec
	)

Sets the given uniform to a Vector3 value.

This will fail if the uniform is not a GLSL vec3 variable.

Parameters

name	The name of the uniform
vec	The value for the uniform

◆ pushVec3() [2/2]

void cugl::graphics::GraphicsShader::pushVec3	(	const std::string	name,
		float	x,
		float	y,
		float	z
	)

Sets the given uniform to the given values

This will fail if the uniform is not a GLSL vec3 variable.

Parameters

name	The name of the uniform
x	The x-value for the vector
y	The x-value for the vector
z	The z-value for the vector

◆ pushVec4() [1/3]

void cugl::graphics::GraphicsShader::pushVec4	(	const std::string	name,
		const Quaternion &	quat
	)

Sets the given uniform to a quaternion.

This will fail if the uniform is not a GLSL vec4 variable.

Parameters

name	The name of the uniform
quat	The value for the uniform

◆ pushVec4() [2/3]

void cugl::graphics::GraphicsShader::pushVec4	(	const std::string	name,
		const Vec4 &	vec
	)

Sets the given uniform to a Vector4 value.

This will fail if the uniform is not a GLSL vec4 variable.

Parameters

name	The name of the uniform
vec	The value for the uniform

◆ pushVec4() [3/3]

void cugl::graphics::GraphicsShader::pushVec4	(	const std::string	name,
		float	x,
		float	y,
		float	z,
		float	w
	)

Sets the given uniform to the given values

This will fail if the uniform is not a GLSL vec4 variable.

Parameters

name	The name of the uniform
x	The x-value for the vector
y	The x-value for the vector
z	The z-value for the vector
w	The z-value for the vector

◆ setAttributeStride()

void cugl::graphics::GraphicsShader::setAttributeStride	(	Uint32	group,
		size_t	stride
	)

Sets the stride for the given attribute group

By default, the attribute stride is inferred from the declarations. However, sometimes we wish to use a VertexBuffer that contains more attributes than what is used by this shader. In that case, we need explicitly set the stride of the attribute group.

Parameters

group	The attribute group
stride	The stride of the attribute group

◆ setBackStencilState()

void cugl::graphics::GraphicsShader::setBackStencilState ( const StencilState & stencil )

Sets the back-facing stencil state for this graphics shader

This setting will only apply to triangles that are back-facing. Use setFrontStencilState to affect front-facing triangles.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

stencil The back-facing stencil state

◆ setBlendMode()

void cugl::graphics::GraphicsShader::setBlendMode ( BlendMode mode )

Sets the blending mode for this graphics shader

A blending mode is a predefined color blend setting that sets the color blend state. You cannot determine the blend mode for a shader after it is set. You can only get the color blend state for that mode with the method getBlendState.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

mode	The blending mode for this shader

◆ setBlendState()

void cugl::graphics::GraphicsShader::setBlendState ( const BlendState & blend )

Sets the color blend state for this graphics shader

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

blend The color blend state

◆ setBlock()

void cugl::graphics::GraphicsShader::setBlock	(	const std::string	name,
		Uint32	block
	)

Sets the active block of the associated resource buffer

If the type of the resource is not ResourceType#MULTI_BUFFER or ResourceType#MULTI_STORAGE, this method will fail. Otherwise, it will change the active block. That block will be used in the next draw call.

Note that if the resource variable refers to an array of buffers, all buffers must have the same block. Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
block	The block to use

◆ setColorMask()

void cugl::graphics::GraphicsShader::setColorMask ( Uint8 mask )

Sets the color mask for stencils in this graphics shader

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

mask	The stencil color mask

◆ setCullMode()

void cugl::graphics::GraphicsShader::setCullMode ( CullMode mode )

Sets the triangle culling mode for this graphics shader

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

mode	The triangle culling mode

◆ setDepthFunc()

void cugl::graphics::GraphicsShader::setDepthFunc ( CompareOp func )

Sets the depth comparions function for this graphics shader

If depth testing is enabled, the graphics shader will discard any fragments that fail this comparison.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

func	The depth comparions function

◆ setDrawMode()

void cugl::graphics::GraphicsShader::setDrawMode ( DrawMode mode )

Sets the draw mode for this graphics shader

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

mode	The shader draw mode

◆ setFrontFace()

void cugl::graphics::GraphicsShader::setFrontFace ( FrontFace face )

Sets the front-facing orientation for triangles

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

face	The front-facing orientation for triangles

◆ setFrontStencilState()

void cugl::graphics::GraphicsShader::setFrontStencilState ( const StencilState & stencil )

Sets the font-facing stencil state for this graphics shader

This setting will only apply to triangles that are front-facing. Use setBackStencilState to affect back-facing triangles.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

stencil The font-facing stencil state

◆ setImage()

void cugl::graphics::GraphicsShader::setImage	(	const std::string	name,
		const std::shared_ptr< Image > &	image
	)

Sets the image for the given resource variable

VULKAN ONLY: This method will fail if the variable does not refer to an image (a texture2D in GLSL), or if the value is nullptr. If the variable refers to an array of images, all slots will be assigned to this image.

Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
image	The image for the resource

◆ setImageArray()

void cugl::graphics::GraphicsShader::setImageArray	(	const std::string	name,
		const std::shared_ptr< ImageArray > &	array
	)

Sets the image array for the given resource variable

VULKAN ONLY: This method will fail if the variable does not refer to an image array (a texture2DArray in GLSL), or if the value is nullptr. If the variable refers to an array of image arrays, all slots will be assigned to this image array.

Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
array	The image array for the resource

◆ setImageArrays()

void cugl::graphics::GraphicsShader::setImageArrays	(	const std::string	name,
		const std::vector< std::shared_ptr< ImageArray > > &	arrays
	)

Sets the image arrays for the given resource variable

VULKAN ONLY: This method will fail if the variable does not refer to an image array (a texture2DArray in GLSL), or if the vector is empty. If the vector is larger than the number of images referenced by this variable, then the image arrays past the limit are ignored. If the vector is smaller, then the missing positions will be replaced by the last image array.

Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
arrays	The image arrays for the resource

◆ setImages()

void cugl::graphics::GraphicsShader::setImages	(	const std::string	name,
		const std::vector< std::shared_ptr< Image > > &	images
	)

Sets the images for the given resource variable

VULKAN ONLY: This method will fail if the variable does not refer to an image (a texture2D in GLSL), or if the vector is empty. If the vector is larger than the number of images referenced by this variable, then the images past the limit are ignored. If the vector is smaller, then the missing positions will be replaced by the last image.

Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
images	The images for the resource

◆ setIndices()

void cugl::graphics::GraphicsShader::setIndices ( const std::shared_ptr< IndexBuffer > & indices )

Sets the indices for the shader

These indices define the drawing topology and are applied to all attached vertex buffers that are not members of an instanced group. They define the behavior of the methods drawIndexed and drawInstancesIndexed.

Parameters

indices The index buffer

◆ setInstanced()

void cugl::graphics::GraphicsShader::setInstanced	(	Uint32	group,
		bool	instanced
	)

Sets the given attribute group as instanced.

Instancing must be applied to a group, as it affects all vertices in a single VertexBuffer. Hence it is essentially a property of the buffer itself. An instanced vertex buffer processes vertices at once per instance instead of once per vertex.

This can be called either before or after declareAttribute defines any attributes for this group. However, if there are no attributes declared for this group at the time of compile, this will have no effect.

Parameters

group	The attribute group
instanced	Whether to instance the group

◆ setLineWidth()

void cugl::graphics::GraphicsShader::setLineWidth ( float width )

Sets the line width for this graphics shader

VULKAN ONLY: This feature is not supported in OpenGL. In Vulkan this defines the pixel width of a line.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

width The line width

◆ setRenderPass()

void cugl::graphics::GraphicsShader::setRenderPass ( const std::shared_ptr< RenderPass > & pass )

inline

Sets the default render pass for this shader

The render pass determines what FrameBuffer objects can be used with this graphics shader. The RenderPass of the framebuffer must be compatible with this renderpass as determined by RenderPass#isCompatible.

If this value is not set, or is nullptr, then graphics shader is compiled to be used with the display. It can still be used with any compatible FrameBuffer, which is any framebuffer with one color attachment and a depth buffer.

Parameters

pass	The default render pass for this shader

◆ setSampler()

void cugl::graphics::GraphicsShader::setSampler	(	const std::string	name,
		const std::shared_ptr< Sampler > &	sampler
	)

Sets the sampler for the given resource variable

VULKAN ONLY: This method will fail if the variable does not refer to a sampler (a sampler in GLSL), or if the value is nullptr. If the variable refers to an array of samplers, all slots will be assigned to this sampler.

Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
sampler	The sampler for the resource

◆ setSamplers()

void cugl::graphics::GraphicsShader::setSamplers	(	const std::string	name,
		const std::vector< std::shared_ptr< Sampler > > &	samplers
	)

Sets the samplers for the given resource variable

VULKAN ONLY: This method will fail if the variable does not refer to a sampler (a sampler in GLSL), or if the value is nullptr. If the vector is larger than the number of samplers referenced by this variable, then the samplers past the limit are ignored. If the vector is smaller, then the missing positions will be replaced by nullptr (potentially causing the pipeline to crash).

Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
samplers	The samplers for the resource

◆ setStencilMode()

void cugl::graphics::GraphicsShader::setStencilMode ( StencilMode mode )

Sets the stencil mode for this graphics shader

A stencil mode is a predefined stencil setting that applies to both front-facing and back-facing triangles. You cannot determine the stencil mode for a shader after it is set. You can only get the stencil state for that mode with the methods getFrontStencilState and getBackStencilState.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

mode	The stencil mode for this shader

◆ setStencilState()

void cugl::graphics::GraphicsShader::setStencilState ( const StencilState & stencil )

Sets the stencil state (both front and back) for this graphics shader

This method will change both the front and back stencil states to the given value. You can access the individual settings with the methods getFrontStencilState and getBackStencilState.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Parameters

stencil The (front and back) stencil state

◆ setStorageBuffer()

void cugl::graphics::GraphicsShader::setStorageBuffer	(	const std::string	name,
		const std::shared_ptr< StorageBuffer > &	buffer
	)

Sets the storage buffer for the given resource variable

VULKAN ONLY: This method will fail if the variable does not refer to a storage buffer or if the value is nullptr. If the resource variable refers to an array of storage buffers, then this buffer will be assigned to all positions in the array.

If the storage buffer is composed of more than one block (e.g. it has type ResourceType#MULTI_STORAGE), the shader will initially start at block 0. To switch the block, use setBlock.

Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
buffer	The storage buffer for the resource

◆ setStorageBuffers()

void cugl::graphics::GraphicsShader::setStorageBuffers	(	const std::string	name,
		const std::vector< std::shared_ptr< StorageBuffer > > &	buffers
	)

Sets the storage buffer array for the given resource variable

VULKAN ONLY: This method will fail if the variable does not refer to a storage buffer or if the vector is empty. If the vector is larger than the number of buffers referenced by this variable, then the buffers past the limit are ignored. If the vector is smaller, then the missing positions will be replaced by the last buffer.

If the storage buffers are composed of more than one block (e.g. they have type ResourceType#MULTI_STORAGE), the shader will initially start at block 0. To switch the block, use setBlock. Note that all storage buffers in an array must have the same block count.

Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
buffers	The storage buffers for the resource

◆ setTexture()

void cugl::graphics::GraphicsShader::setTexture	(	const std::string	name,
		const std::shared_ptr< Texture > &	texture
	)

Sets the texture for the given resource variable

This method will fail if the variable does not refer to a texture (a sampler2D in GLSL), or if the value is nullptr. If the variable refers to an array of textures, all slots will be assigned to this texture.

Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
texture	The texture for the resource

◆ setTextureArray()

void cugl::graphics::GraphicsShader::setTextureArray	(	const std::string	name,
		const std::shared_ptr< TextureArray > &	array
	)

Sets the texture array for the given resource variable

This method will fail if the variable does not refer to a texture array (a sampler2DArray in GLSL), or if the value is nullptr. If the variable refers to an array of texture arrays, all slots will be assigned to this texture array.

Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
array	The texture array for the resource

◆ setTextureArrays()

void cugl::graphics::GraphicsShader::setTextureArrays	(	const std::string	name,
		const std::vector< std::shared_ptr< TextureArray > > &	arrays
	)

Sets the texture arrays for the given resource variable

This method will fail if the variable does not refer to a texture array (a sampler2DArray in GLSL), or if the vector is empty. If the vector is larger than the number of texture arrays referenced by this variable, then the texture arrays past the limit are ignored. If the array is smaller, then the missing positions will be replaced by the last texture array.

Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
arrays	The texture arrays for the resource

◆ setTextures()

void cugl::graphics::GraphicsShader::setTextures	(	const std::string	name,
		const std::vector< std::shared_ptr< Texture > > &	textures
	)

Sets the textures for the given resource variable

This method will fail if the variable does not refer to a texture (a sampler2D in GLSL), or if the vector is empty. If the vector is larger than the number of textures referenced by this variable, then the textures past the limit are ignored. If the vector is smaller, then the missing positions will be replaced by the last texture.

Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
textures	The textures for the resource

◆ setUniformBuffer()

void cugl::graphics::GraphicsShader::setUniformBuffer	(	const std::string	name,
		const std::shared_ptr< UniformBuffer > &	buffer
	)

Sets the uniform buffer for the given resource variable

This method will fail if the variable does not refer to a uniform buffer (e.g. a std140 buffer in OpenGL, or a uniform in Vulkan) or if the value is nullptr. If the resource variable refers to an array of uniform buffers, then this buffer will be assigned to all positions in the array.

If the uniform buffer is composed of more than one block (e.g. it has type ResourceType#MULTI_BUFFER), the shader will initially start at block 0. To switch the block, use setBlock.

Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
buffer	The uniform buffer for the resource

◆ setUniformBuffers()

void cugl::graphics::GraphicsShader::setUniformBuffers	(	const std::string	name,
		const std::vector< std::shared_ptr< UniformBuffer > > &	buffers
	)

Sets the uniform buffer array for the given resource variable

This method will fail if the variable does not refer to a uniform buffer (e.g. a std140 buffer in OpenGL, or a uniform in Vulkan) or if the vector is empty. If the vector is larger than the number of buffers referenced by this variable, then the buffers past the limit are ignored. If the vector is smaller, then the missing positions will be replaced by the last buffer.

If the uniform buffers are composed of more than one block (e.g. they have type ResourceType#MULTI_BUFFER), the shader will initially start at block 0. To switch the block, use setBlock. Note that all buffers in an array must use the same block.

Setting this value is stateful, in that it will persist across render passes.

Parameters

name	The name of the resource
buffers	The uniform buffers for the resource

◆ setVertices()

void cugl::graphics::GraphicsShader::setVertices	(	Uint32	group,
		const std::shared_ptr< VertexBuffer > &	vertices
	)

Sets the vertex buffer for an attribute group

Attribute groups must be defined in the AttributeDef provided at compile time. All attributes in the vertex buffer must share the same binding group.

Elements in the vertex buffer correspond to vertices. If the attribute group is instanced, these vertices will be indexed by the drawing instance. Otherwise, they will be indexed by the IndexBuffer.

Parameters

group	The attribute group
vertices	The vertex buffer

◆ setViewScissor() [1/2]

void cugl::graphics::GraphicsShader::setViewScissor ( const Rect & scissor )

inline

Sets the AABB scissor value of this graphics shader

This is a drawing primitive that is distinct from the Scissor class. That is a rotational scissor supported by SpriteBatch.

Changing this value has no immediate effect if it is called in the middle of a render pass. Instead, it will be applies at the next call to begin.

Parameters

scissor The graphics shader scissor

◆ setViewScissor() [2/2]

void cugl::graphics::GraphicsShader::setViewScissor	(	Uint32	x,
		Uint32	y,
		Uint32	w,
		Uint32	h
	)

Sets the AABB scissor value of this graphics shader

This is a drawing primitive that is distinct from the Scissor class. That is a rotational scissor supported by SpriteBatch.

Changing this value has no immediate effect if it is called in the middle of a render pass. Instead, it will be applies at the next call to begin.

Parameters

x	The x-coordinate of the scissor origin
y	The y-coordinate of the scissor origin
w	The scissor width
h	The scissor height

◆ usesBlending()

bool cugl::graphics::GraphicsShader::usesBlending ( ) const

Returns whether color blending is currently enabled in this shader.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Returns: whether color blending is currently enabled in this shader.

◆ usesDepthTest()

bool cugl::graphics::GraphicsShader::usesDepthTest ( ) const

Returns whether depth testing is currently enabled in this shader.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Returns: whether depth testing is currently enabled in this shader.

◆ usesDepthWrite()

bool cugl::graphics::GraphicsShader::usesDepthWrite ( ) const

Returns whether depth writing is currently enabled in this shader.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Returns: whether depth writing is currently enabled in this shader.

◆ usesStencilTest()

bool cugl::graphics::GraphicsShader::usesStencilTest ( ) const

Returns whether stencil testing is currently enabled in this shader.

It is possible to set this value before the call to {@ compile}. In that case, the value set is the default for this graphics shader.

Returns: whether stencil testing is currently enabled in this shader.

◆ usesViewScissor()

bool cugl::graphics::GraphicsShader::usesViewScissor ( ) const

Returns true if the view scissor is enabled in this graphics shader.

This is a drawing primitive that is distinct from the Scissor class. That is a rotational scissor supported by SpriteBatch.

Changing this value has no immediate effect if it is called in the middle of a render pass. Instead, it will be applies at the next call to begin.

Returns: true if the view scissor is enabled in this graphics shader.

◆ validate()

bool cugl::graphics::GraphicsShader::validate ( )

protected

Validates the graphics shader prior to compilation

One of the things that we enforce is that attribute groups be continguous. If there is an attribute group for n and n+2, but not n+1, then this method will fail.

Returns: true if validation was successful.

Member Data Documentation

◆ _attachments

size_t cugl::graphics::GraphicsShader::_attachments

protected

The number of color attachments

◆ _attributes

std::unordered_map<std::string, AttributeDef> cugl::graphics::GraphicsShader::_attributes

protected

The attribute definitions for this shader

◆ _attrStride

std::vector<Uint32> cugl::graphics::GraphicsShader::_attrStride

protected

The (manually defined) stride for each attribute group

◆ _data

GraphicsShaderData* cugl::graphics::GraphicsShader::_data

protected

The graphics API implementation of this shader

◆ _fragModule

ShaderSource cugl::graphics::GraphicsShader::_fragModule

protected

The source for the fragment shader

◆ _framebuffer

std::shared_ptr<FrameBuffer> cugl::graphics::GraphicsShader::_framebuffer

protected

The current active framebuffer (nullptr to draw to display)

◆ _indices

std::shared_ptr<IndexBuffer> cugl::graphics::GraphicsShader::_indices

protected

The currently attached index buffers

◆ _initialGroup

Uint32 cugl::graphics::GraphicsShader::_initialGroup

protected

The initial attribute group

◆ _instances

std::unordered_set<Uint32> cugl::graphics::GraphicsShader::_instances

protected

The instanced attribute groups

◆ _renderpass

std::shared_ptr<RenderPass> cugl::graphics::GraphicsShader::_renderpass

protected

The render pass for this shader

◆ _resources

std::unordered_map<std::string, ResourceDef> cugl::graphics::GraphicsShader::_resources

protected

The resource definitions of this shader

◆ _uniforms

std::unordered_map<std::string, UniformDef> cugl::graphics::GraphicsShader::_uniforms

protected

The uniform definitions of this shader

◆ _values

std::unordered_map<std::string, ResourceData*> cugl::graphics::GraphicsShader::_values

protected

The currently attached resources

◆ _vertices

std::vector<std::shared_ptr<VertexBuffer> > cugl::graphics::GraphicsShader::_vertices

protected

The currently attached vertex buffers

◆ _vertModule

ShaderSource cugl::graphics::GraphicsShader::_vertModule

protected

The source for the vertex shader

◆ g_shader

std::shared_ptr<GraphicsShader> cugl::graphics::GraphicsShader::g_shader

staticprotected

The active shader (if any)

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

/Users/wmwhite/Developer/CUGL/include/cugl/graphics/CUGraphicsShader.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ GraphicsShader()

◆ ~GraphicsShader()

Member Function Documentation

◆ alloc()

◆ begin() [1/2]

◆ begin() [2/2]

◆ compile()

◆ declareAttribute()

◆ declareResource()

◆ declareUniform()

◆ dispose()

◆ draw()

◆ drawIndexed()

◆ drawInstances()

◆ drawInstancesIndexed()

◆ enableBlending()

◆ enableDepthTest()

◆ enableDepthWrite()

◆ enableStencilTest()

◆ enableViewScissor()

◆ end()

◆ flush()

◆ getAttributeDef()

◆ getBackStencilState()

◆ getBlendState()

◆ getBlock()

◆ getColorMask()

◆ getCullMode()

◆ getDepthFunc()

◆ getDrawMode()

◆ getFrontFace()

◆ getFrontStencilState()

◆ getImage()

◆ getImageArray()

◆ getImageArrays()

◆ getImages()

◆ getIndices()

◆ getLineWidth()

◆ getRenderPass()

◆ getResourceDef()

◆ getSampler()

◆ getSamplers()

◆ getStorageBuffer()

◆ getStorageBuffers()

◆ getTexture()

◆ getTextureArray()

◆ getTextureArrays()

◆ getTextures()

◆ getUniformBuffer()

◆ getUniformBuffers()

◆ getUniformDef()

◆ getVertices()

◆ getViewScissor()

◆ init()

◆ isCompatible()

◆ isReady()

◆ push() [1/2]

◆ push() [2/2]

◆ pushColor4() [1/2]

◆ pushColor4() [2/2]

◆ pushColor4f() [1/2]

◆ pushColor4f() [2/2]

◆ pushFloat()

◆ pushInt()

◆ pushIVec2()

◆ pushIVec3()

◆ pushIVec4()

◆ pushMat2() [1/2]

◆ pushMat2() [2/2]

◆ pushMat3() [1/2]

◆ pushMat3() [2/2]

◆ pushMat4() [1/2]

◆ pushMat4() [2/2]