CUGL 4.0
Cornell University Game Library
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
cugl::graphics::ComputeShader Class Reference

#include <CUComputeShader.h>

Inheritance diagram for cugl::graphics::ComputeShader:

Public Member Functions

 ComputeShader ()
 
 ~ComputeShader ()
 
virtual void dispose ()
 
virtual bool init (const ShaderSource &source)
 
IVec3 getDimension () const
 
void setDimension (const IVec3 dimension)
 
void setDimension (Uint32 x, Uint32 y, Uint32 z)
 
bool declareUniform (const std::string name, const UniformDef &def)
 
const UniformDefgetUniformDef (const std::string name) const
 
void setConstant (const std::string name, const GLSLConstant &spec)
 
const GLSLConstantgetConstant (const std::string name) const
 
bool declareInput (const std::string name, const ResourceDef &def)
 
bool declareOutput (const std::string name, const ResourceDef &def)
 
const ResourceDefgetResourceDef (const std::string name) const
 
bool isWriteable (const std::string name) const
 
bool compile ()
 
bool isReady () 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< UniformBuffergetUniformBuffer (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< StorageBuffergetStorageBuffer (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) const
 
void setVertexBuffer (const std::string name, const std::shared_ptr< VertexBuffer > &buffer)
 
const std::shared_ptr< VertexBuffergetVertexBuffer (const std::string name) const
 
void setIndexBuffer (const std::string name, const std::shared_ptr< IndexBuffer > &buffer)
 
const std::shared_ptr< IndexBuffergetIndexBuffer (const std::string name) const
 
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< TexturegetTexture (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< TextureArraygetTextureArray (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< ImagegetImage (const std::string name)
 
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< ImageArraygetImageArray (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< SamplergetSampler (const std::string name)
 
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 end ()
 
void dispatch (Uint32 x=1, Uint32 y=1, Uint32 z=1)
 

Static Public Member Functions

static std::shared_ptr< ComputeShaderalloc (const ShaderSource &source)
 

Protected Member Functions

void createInputs (const std::string name, ResourceDef def)
 
void createOutputs (const std::string name, ResourceDef def)
 
void flush ()
 

Protected Attributes

ComputeShaderData * _data
 
ShaderSource _compModule
 
IVec3 _dimension
 
std::unordered_map< std::string, GLSLConstant_constants
 
std::unordered_map< std::string, UniformDef_uniforms
 
std::unordered_map< std::string, ResourceDef_inputs
 
std::unordered_map< std::string, ResourceDef_outputs
 
std::vector< ImageData * > _transitions
 
std::vector< uint8_t > _constvalues
 
std::unordered_map< std::string, ResourceData * > _invalues
 
std::unordered_map< std::string, ResourceData * > _outvalues
 

Static Protected Attributes

static std::shared_ptr< ComputeShaderg_shader
 

Detailed Description

This class defines a GLSL compute shader.

VULKAN ONLY: This class compiles any well-defined GLSL compute shader. Note that CUGL only supports compute shaders in Vulkan (due to the OpenGL limitations of Apple platforms). Attempts to allocate an object of this type in OpenGL will fail.

Compute shaders only have a single shader module. For input, they support push constants, and any ResourceType. For output, we only support StorageBuffer, VertexBuffer, IndexBuffer and Image objects with compute access.

Note that it is never safe for input and output to be the same resources. If you need to update a data-set, such as a storage buffer containing particles, you should set up a ping-pong buffer to guarantee safety.

While Vulkan is multithreaded, CUGL shader objects can only be used on the main thread (due to synchronization constraints). Using them outside of the main application loop is undefined. In addition, compute shaders may not be used in the Application#draw method. They can only be used in one of the update methods such as Application#update, Application#preUpdate, Application#fixedUpdate or Application#postUpdate.

Constructor & Destructor Documentation

◆ ComputeShader()

cugl::graphics::ComputeShader::ComputeShader ( )
inline

Creates an uninitialized compute shader with no source.

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

◆ ~ComputeShader()

cugl::graphics::ComputeShader::~ComputeShader ( )
inline

Deletes this shader, disposing all resources.

Member Function Documentation

◆ alloc()

static std::shared_ptr< ComputeShader > cugl::graphics::ComputeShader::alloc ( const ShaderSource source)
inlinestatic

Returns a new compute shader with the given shader 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
sourceThe source for the compute shader.
Returns
a new compute shader with the given vertex and fragment source.

◆ begin()

void cugl::graphics::ComputeShader::begin ( )

Begins a dispatch pass with this shader for the application.

Once this method is called, no other compute shader can perform a dispatch pass. You must complete this dispatch pass with end before starting a new pass.

Note that it is only safe to call this method within the scope of the Application#update method, or any of the deterministic update methods such as Application#preUpdate, Application#fixedUpdate, or Application#postUpdate. It is not safe to call this method during Application#draw. This is due to limitations on the implicit rendering queue in CUGL.

◆ compile()

bool cugl::graphics::ComputeShader::compile ( )

Compiles this compute shader for use

All variables (uniforms, input resources, and output resources) should be declared before compilation. 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.

◆ createInputs()

void cugl::graphics::ComputeShader::createInputs ( const std::string  name,
ResourceDef  def 
)
protected

Create the input data structures for the given definition

Parameters
nameThe resource name
defThe resource definition

◆ createOutputs()

void cugl::graphics::ComputeShader::createOutputs ( const std::string  name,
ResourceDef  def 
)
protected

Create the output data structures for the given definition

Parameters
nameThe resource name
defThe resource definition

◆ declareInput()

bool cugl::graphics::ComputeShader::declareInput ( const std::string  name,
const ResourceDef def 
)

Declares an shader input uniform.

Input uniforms include resources such as uniform buffers, storage buffers, and images. In order to be used, each resource must be declared before the compute 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 setImage.

Input uniforms are always read-only. This method can fail if the resource has already been declared.

Parameters
nameThe resource name
defThe resource type, size, and location
Returns
true if the declaration was successful

◆ declareOutput()

bool cugl::graphics::ComputeShader::declareOutput ( const std::string  name,
const ResourceDef def 
)

Declares an shader ouput uniform.

Output uniforms are resources that can be written to by a compute shader. Currently we only support Image, VertexBuffer, IndexBuffer and StorageBuffer objects with access type compute.

In order to be used, each resource must be declared before the compute 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 setImage.

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

Parameters
nameThe resource name
defThe resource type, size, and location
Returns
true if the declaration was successful

◆ declareUniform()

bool cugl::graphics::ComputeShader::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 compute shader via any of the push methods.

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

Parameters
nameThe uniform name
defThe uniform type, size, and location
Returns
true if the declaration was successful

◆ dispatch()

void cugl::graphics::ComputeShader::dispatch ( Uint32  x = 1,
Uint32  y = 1,
Uint32  z = 1 
)

Dispatches a global workgroup on this compute shader

Each workgroup with have getDimension many local threads. The dimension must be non-zero along each axis

Parameters
xNumber of workgroups along the x dimension
yNumber of workgroups along the y dimension
zNumber of workgroups along the z dimension

◆ dispose()

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

Deletes the shader and resets all attributes.

You must reinitialize the shader to use it.

◆ end()

void cugl::graphics::ComputeShader::end ( )

Ends the dispatch pass for this shader.

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

Note that once this method is called, it is not safe to make futher modifications to any output resources.

◆ flush()

void cugl::graphics::ComputeShader::flush ( )
protected

Updates all descriptors and buffers before computation.

◆ getBlock()

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

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 call to dispatch.

Parameters
nameThe name of the resource
Returns
the active block of the associated resource buffer

◆ getConstant()

const GLSLConstant * cugl::graphics::ComputeShader::getConstant ( const std::string  name) const

Returns the information for a specialization constant

Specialization constants are assigned to the compute shader at compile time. This value can be reassigned any time before a call to compile, but cannot be changed once the compute shader is complete.

If there is no constant associated with the given name, this method returns nullptr.

Parameters
nameThe constant name
Returns
the information for a specialization constant

◆ getDimension()

IVec3 cugl::graphics::ComputeShader::getDimension ( ) const
inline

Returns the local group dimension of this compute shader

Setting this value has no effect on the compute shader. The dimension of a compute shader is entirely deteremined by its shader source. However, setting this value is useful for debugging.

Returns
the local group dimension of this compute shader

◆ getImage()

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

Returns the image for the given resource variable

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 compute passes. Note that an image can either be an input or an output resource. If name is an output variable, then the image must have compute access or this method will fail.

Parameters
nameThe name of the resource
Returns
the image for the given resource variable

◆ getImageArray()

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

Returns the image array for the given resource variable

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 compute passes. Note that image arrays (as opposed to images) are currently read-only in compute shaders.

Parameters
nameThe name of the resource
Returns
the image array for the given resource variable

◆ getImageArrays()

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

Returns the image arrays for the given resource variable

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

Any image array assigned to a name is stateful, in that it will persist across compute passes. Note that image arrays (as opposed to images) are currently read-only in compute shaders.

Parameters
nameThe name of the resource
Returns
the image arrays for the given resource variable

◆ getImages()

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

Returns the images for the given resource variable

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

Any image assigned to a name is stateful, in that it will persist compute passes. Note that an image can either be an input or an output resource. If name is an output variable, then the image must have compute access or this method will fail.

Parameters
nameThe name of the resource
Returns
the images for the given resource variable

◆ getIndexBuffer()

const std::shared_ptr< IndexBuffer > cugl::graphics::ComputeShader::getIndexBuffer ( const std::string  name) const

Returns the index buffer for the given resource variable

Compute shaders do not use index buffers as inputs, but they can use them as outputs. This is particularly useful for tesselation, where a compute shader is used to fill the contents of the index buffer.

Any IndexBuffer returned by this method must have compute access.

Parameters
nameThe name of the resource
Returns
the index buffer for the given resource variable

◆ getResourceDef()

const ResourceDef * cugl::graphics::ComputeShader::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, or if it does not correspond to an input variable, this method returns nullptr.

This method does not distinguish input resources from output resources.

Parameters
nameThe resource name
Returns
the resource definition for the given variable name.

◆ getSampler()

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

Returns the sampler for the given resource variable

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 compute passes. Note that samplers are read-only in compute shaders.

Parameters
nameThe name of the resource
Returns
the sampler for the given resource variable

◆ getSamplers()

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

Returns the samplers for the given resource variable

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 compute passes. Note that samplers are read-only in compute shaders.

Parameters
nameThe name of the resource
Returns
the samplers for the given resource variable

◆ getStorageBuffer()

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

Returns the storage buffer for the given resource variable

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.

Storage buffers may be used either an input our output in a compute shader. Output buffers should have an access type that allows write access by the compute shader. Any buffer assigned to a name is stateful, in that it will persist across compute passes.

Parameters
nameThe name of the resource
Returns
the storage buffer for the given resource variable

◆ getStorageBuffers()

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

Returns the storage buffers for the given resource variable

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

Storage buffers may be used either an input our output in a compute shader. Output buffers should have an access type that allows write access by the compute shader. Any buffer assigned to a name is stateful, in that it will persist across compute passes.

Parameters
nameThe name of the resource
Returns
the storage buffers for the given resource variable

◆ getTexture()

const std::shared_ptr< Texture > cugl::graphics::ComputeShader::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 dispatch calls. Note that textures (which include both an image and a sampler) are read-only in compute shaders.

Parameters
nameThe name of the resource
Returns
the texture for the given resource variable

◆ getTextureArray()

const std::shared_ptr< TextureArray > cugl::graphics::ComputeShader::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 compute passes. Note that texture arrays (which include both an image array and a sampler) are read-only in compute shaders.

Parameters
nameThe name of the resource
Returns
the texture array for the given resource variable

◆ getTextureArrays()

const std::vector< std::shared_ptr< TextureArray > > cugl::graphics::ComputeShader::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 compute passes. Note that texture arrays (which include both an image array and a sampler) are read-only in compute shaders.

Parameters
nameThe name of the resource
Returns
the texture arrays for the given resource variable

◆ getTextures()

const std::vector< std::shared_ptr< Texture > > cugl::graphics::ComputeShader::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 dispatch calls. Note that textures (which include both an image and a sampler) are read-only in compute shaders.

Parameters
nameThe name of the resource
Returns
the textures for the given resource variable

◆ getUniformBuffer()

const std::shared_ptr< UniformBuffer > cugl::graphics::ComputeShader::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 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 compute passes. Note that uniform buffers are always read-only in CUGL compute shaders.

Parameters
nameThe name of the resource
Returns
the uniform buffer for the given resource variable

◆ getUniformBuffers()

const std::vector< std::shared_ptr< UniformBuffer > > cugl::graphics::ComputeShader::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 then this method will return an empty vector.

Any buffer assigned to a name is stateful, in that it will persist across compute passes. Note that uniform buffers are always read-only in CUGL compute shaders.

Parameters
nameThe name of the resource
Returns
the uniform buffers for the given resource variable

◆ getUniformDef()

const UniformDef * cugl::graphics::ComputeShader::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
nameThe attribute name
Returns
the uniform definition for the given variable name.

◆ getVertexBuffer()

const std::shared_ptr< VertexBuffer > cugl::graphics::ComputeShader::getVertexBuffer ( const std::string  name) const

Returns the vertex buffer for the given resource variable

Compute shaders do not use vertex buffers as inputs, but they can use them as outputs. This is particularly useful for particle systems, where a compute shader is used to fill the contents of the vertex buffer.

Any VertexBuffer returned by this method must have compute access.

Parameters
nameThe name of the resource
Returns
the vertex buffer for the given resource variable

◆ init()

virtual bool cugl::graphics::ComputeShader::init ( const ShaderSource source)
virtual

Initializes this shader with the given shader 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
sourceThe source for the compute shader.
Returns
true if initialization was successful.

◆ isReady()

bool cugl::graphics::ComputeShader::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.

◆ isWriteable()

bool cugl::graphics::ComputeShader::isWriteable ( const std::string  name) const

Returns true if the resource variable is writeable

A writeable resource is one that has been declared by the method declareOutput. If the variable does not exist or was declared with another method, this method returns false.

Parameters
nameThe resource name
Returns
the resource definition for the given variable name.

◆ push() [1/2]

template<typename T >
void cugl::graphics::ComputeShader::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
nameThe uniform name
valueThe uniform value

◆ push() [2/2]

void cugl::graphics::ComputeShader::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
nameThe uniform name
dataThe uniform data

◆ pushColor4() [1/2]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
colorThe value for the uniform

◆ pushColor4() [2/2]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
redThe uniform red value
greenThe uniform green value
blueThe uniform blue value
alphaThe uniform alpha value

◆ pushColor4f() [1/2]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
colorThe value for the uniform

◆ pushColor4f() [2/2]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
redThe uniform red value
greenThe uniform green value
blueThe uniform blue value
alphaThe uniform alpha value

◆ pushFloat()

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
valueThe value for the uniform

◆ pushInt()

void cugl::graphics::ComputeShader::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 this method does nothing if it is not invoked during an active begin/end pair. This method does not cache uniforms for later.

Parameters
nameThe name of the uniform
valueThe value for the uniform

◆ pushIVec2()

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
xThe x-value for the vector
yThe x-value for the vector

◆ pushIVec3()

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
xThe x-value for the vector
yThe x-value for the vector
zThe z-value for the vector

◆ pushIVec4()

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
xThe x-value for the vector
yThe x-value for the vector
zThe z-value for the vector
wThe z-value for the vector

◆ pushMat2() [1/2]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
matThe value for the uniform

◆ pushMat2() [2/2]

void cugl::graphics::ComputeShader::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.

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

Parameters
nameThe name of the uniform
arrayThe values for the uniform

◆ pushMat3() [1/2]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
matThe value for the uniform

◆ pushMat3() [2/2]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
arrayThe values for the uniform

◆ pushMat4() [1/2]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
arrayThe values for the uniform

◆ pushMat4() [2/2]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
matThe value for the uniform

◆ pushUInt()

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
valueThe value for the uniform

◆ pushUVec2()

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
xThe x-value for the vector
yThe x-value for the vector

◆ pushUVec3()

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
xThe x-value for the vector
yThe x-value for the vector
zThe z-value for the vector

◆ pushUVec4()

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
xThe x-value for the vector
yThe x-value for the vector
zThe z-value for the vector
wThe z-value for the vector

◆ pushVec2() [1/2]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
vecThe value for the uniform

◆ pushVec2() [2/2]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
xThe x-value for the vector
yThe x-value for the vector

◆ pushVec3() [1/2]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
vecThe value for the uniform

◆ pushVec3() [2/2]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
xThe x-value for the vector
yThe x-value for the vector
zThe z-value for the vector

◆ pushVec4() [1/3]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
quatThe value for the uniform

◆ pushVec4() [2/3]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
vecThe value for the uniform

◆ pushVec4() [3/3]

void cugl::graphics::ComputeShader::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.

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
nameThe name of the uniform
xThe x-value for the vector
yThe x-value for the vector
zThe z-value for the vector
wThe z-value for the vector

◆ setBlock()

void cugl::graphics::ComputeShader::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 call to dispatch.

Parameters
nameThe name of the resource
blockThe resource block to use

◆ setConstant()

void cugl::graphics::ComputeShader::setConstant ( const std::string  name,
const GLSLConstant spec 
)

Declares and sets a specialization constant

Specialization constants are assigned to the compute shader at compile time. This value can be reassigned any time before a call to compile, but cannot be changed once the compute shader is complete.

Parameters
nameThe constant name
specThe specialization constant

◆ setDimension() [1/2]

void cugl::graphics::ComputeShader::setDimension ( const IVec3  dimension)
inline

Sets the local group dimension of this compute shader

Setting this value has no effect on the compute shader. The dimension of a compute shader is entirely deteremined by its shader source. However, setting this value is useful for debugging.

Parameters
dimensionThe local group dimension

◆ setDimension() [2/2]

void cugl::graphics::ComputeShader::setDimension ( Uint32  x,
Uint32  y,
Uint32  z 
)
inline

Sets the local group dimension of this compute shader

Setting this value has no effect on the compute shader. The dimension of a compute shader is entirely deteremined by its shader source. However, setting this value is useful for debugging.

Parameters
xThe local group size in the x-dimension
yThe local group size in the y-dimension
zThe local group size in the z-dimension

◆ setImage()

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

Sets the image for the given resource variable

This method will fail is 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 compute passes. Note that an image can either be an input or an output resource. If name is an output variable, then the image must have compute access or this method will fail.

Parameters
nameThe name of the resource
imageThe image for the resource

◆ setImageArray()

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

Sets the image array for the given resource variable

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 compute passes. Note that image arrays (as opposed to images) are currently read-only in compute shaders.

Parameters
nameThe name of the resource
arrayThe image array for the resource

◆ setImageArrays()

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

Sets the image arrays for the given resource variable

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 compute passes. Note that image arrays (as opposed to images) are currently read-only in compute shaders.

Parameters
nameThe name of the resource
arraysThe image arrays for the resource

◆ setImages()

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

Sets the images for the given resource variable

This method will fail is the variable does not refer to an image (a texture2D in GLSL), or if the value is nullptr. 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 nullptr (potentially causing the pipeline to crash).

Setting this value is stateful, in that it will persist across compute passes. Note that an image can either be an input or an output resource. If name is an output variable, then the image must have compute access or this method will fail.

Parameters
nameThe name of the resource
imagesThe images for the resource

◆ setIndexBuffer()

void cugl::graphics::ComputeShader::setIndexBuffer ( const std::string  name,
const std::shared_ptr< IndexBuffer > &  buffer 
)

Sets the index buffer for the given resource variable

Compute shaders do not use index buffers as inputs, but they can use them as outputs. This is particularly useful for tesselation, where a compute shader is used to fill the contents of the index buffer.

Any IndexBuffer set by this method must have compute access.

Parameters
nameThe name of the resource
bufferThe index buffer for the resource

◆ setSampler()

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

Sets the sampler for the given resource variable

This method will fail is 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 compute passes. Note that samplers are read-only in compute shaders.

Parameters
nameThe name of the resource
samplerThe sampler for the resource

◆ setSamplers()

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

Sets the samplers for the given resource variable

This method will fail is 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 compute passes. Note that samplers are read-only in compute shaders.

Parameters
nameThe name of the resource
samplersThe samplers for the resource

◆ setStorageBuffer()

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

Sets the storage buffer for the given resource variable

If the variable does not refer to a storage buffer, then this method will fail. 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.

Storage buffers may be used either an input our output in a compute shader. Output buffers should have an access type that allows write access by the compute shader. Setting this value is stateful, in that it will persist across compute passes.

Parameters
nameThe name of the resource
bufferThe uniform buffer for the resource

◆ setStorageBuffers()

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

Sets the storage buffer array for the given resource variable

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.

Storage buffers may be used either an input our output in a compute shader. Output buffers should have an access type that allows write access by the compute shader. Setting this value is stateful, in that it will persist across compute passes.

Parameters
nameThe name of the resource
buffersThe storage buffers for the resource

◆ setTexture()

void cugl::graphics::ComputeShader::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 compute passes. Note that textures (which include both an image and a sampler) are read-only in compute shaders.

Parameters
nameThe name of the resource
textureThe texture for the resource

◆ setTextureArray()

void cugl::graphics::ComputeShader::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 compute passes. Note that texture arrays (which include both an image array and a sampler) are read-only in compute shaders.

Parameters
nameThe name of the resource
arrayThe texture array for the resource

◆ setTextureArrays()

void cugl::graphics::ComputeShader::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 compute passes. Note that texture arrays (which include both an image array and a sampler) are read-only in compute shaders.

Parameters
nameThe name of the resource
arraysThe texture arrays for the resource

◆ setTextures()

void cugl::graphics::ComputeShader::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 compute passes. Note that textures (which include both an image and a sampler) are read-only in compute shaders.

Parameters
nameThe name of the resource
texturesThe textures for the resource

◆ setUniformBuffer()

void cugl::graphics::ComputeShader::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 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 compute passes. Note that uniform buffers are always read-only in CUGL compute shaders.

Parameters
nameThe name of the resource
bufferThe uniform buffer for the resource

◆ setUniformBuffers()

void cugl::graphics::ComputeShader::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 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 compute passes. Note that uniform buffers are always read-only in CUGL compute shaders.

Parameters
nameThe name of the resource
buffersThe uniform buffers for the resource

◆ setVertexBuffer()

void cugl::graphics::ComputeShader::setVertexBuffer ( const std::string  name,
const std::shared_ptr< VertexBuffer > &  buffer 
)

Sets the vertex buffer for the given resource variable

Compute shaders do not use vertex buffers as inputs, but they can use them as outputs. This is particularly useful for particle systems, where a compute shader is used to fill the contents of the vertex buffer.

Any VertexBuffer set by this method must have compute access.

Parameters
nameThe name of the resource
bufferThe vertex buffer for the resource

Member Data Documentation

◆ _compModule

ShaderSource cugl::graphics::ComputeShader::_compModule
protected

The source for the shader module

◆ _constants

std::unordered_map<std::string,GLSLConstant> cugl::graphics::ComputeShader::_constants
protected

The specialization constant declarations

◆ _constvalues

std::vector<uint8_t> cugl::graphics::ComputeShader::_constvalues
protected

The specialization constant values

This is the data for the specialization constants. The offsets can be determined by the declarations, which are separate.

◆ _data

ComputeShaderData* cugl::graphics::ComputeShader::_data
protected

The graphics API implementation of this shader

◆ _dimension

IVec3 cugl::graphics::ComputeShader::_dimension
protected

The work group dimension

◆ _inputs

std::unordered_map<std::string, ResourceDef> cugl::graphics::ComputeShader::_inputs
protected

The resource input definitions of this shader

◆ _invalues

std::unordered_map<std::string, ResourceData*> cugl::graphics::ComputeShader::_invalues
protected

The currently attached input resources

◆ _outputs

std::unordered_map<std::string, ResourceDef> cugl::graphics::ComputeShader::_outputs
protected

The resource output definitions of this shader

◆ _outvalues

std::unordered_map<std::string, ResourceData*> cugl::graphics::ComputeShader::_outvalues
protected

The currently attached output resources

◆ _transitions

std::vector<ImageData*> cugl::graphics::ComputeShader::_transitions
protected

The images that need to be transitioned

◆ _uniforms

std::unordered_map<std::string, UniformDef> cugl::graphics::ComputeShader::_uniforms
protected

The push-constant definitions of this shader

◆ g_shader

std::shared_ptr<ComputeShader> cugl::graphics::ComputeShader::g_shader
staticprotected

The active shader (if any)


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