Utilities for manipulating GLSL shaders. More...

#include <geogram_gfx/basic/common.h>
#include <geogram/basic/numeric.h>

Classes
struct	GEO::GLSL::GLSLCompileError
	Exception thrown when a GLSL shader fails to compiled. More...

class	GEO::GLSL::Source
	A GLSL source. More...

class	GEO::GLSL::PseudoFileProvider
	A class that can register functions to the GLSL pseudo file system. More...

Namespaces
	GEO
	Global Vorpaline namespace.

Typedefs
typedef void(*	GEO::GLSL::PseudoFile) (PseudoFileProvider *provider, std::vector< Source > &sources)
	A pointer to a function registered as a pseudo file in the GLSL pseudo file system. More...

Functions
void GEOGRAM_GFX_API	GEO::GLSL::initialize ()
	Initializes some GLSL functions and objects. More...

void GEOGRAM_GFX_API	GEO::GLSL::terminate ()
	Terminates GLSL functions and objects. More...

double GEOGRAM_GFX_API	GEO::GLSL::supported_language_version ()
	Gets the supported GLSL language version. More...

void GEOGRAM_GFX_API	GEO::GLSL::register_GLSL_include_file (const std::string &name, const char *source)
	Registers a file in the GLSL pseudo file system. More...

void GEOGRAM_GFX_API	GEO::GLSL::register_GLSL_include_file (const std::string &name, PseudoFile file)
	Registers a pseudo file in the GLSL pseudo file system. More...

const char *	GEO::GLSL::get_GLSL_include_file (const std::string &name)
	Gets a GLSL include file by file name. More...

GLuint GEOGRAM_GFX_API	GEO::GLSL::compile_shader_with_includes (GLenum target, const char source, PseudoFileProvider provider)
	Compiles a shader for a specific target. More...

GLuint GEOGRAM_GFX_API	GEO::GLSL::compile_program_with_includes_no_link (PseudoFileProvider provider, const char shader1, const char shader2=nullptr, const char shader3=nullptr, const char shader4=nullptr, const char shader5=nullptr, const char *shader6=nullptr)
	Compiles a program from shader sources. More...

GLuint GEOGRAM_GFX_API	GEO::GLSL::compile_shader (GLenum target, const char **sources, index_t nb_sources)
	Compiles a shader for a specific target. More...

GLuint GEOGRAM_GFX_API	GEO::GLSL::compile_shader (GLenum target, const char source1, const char source2, const char source3=nullptr, const char source4=nullptr, const char source5=nullptr, const char source6=nullptr, const char source7=nullptr, const char source8=nullptr, const char source9=nullptr, const char source10=nullptr, const char source11=nullptr, const char source12=nullptr, const char source13=nullptr, const char source14=nullptr, const char source15=nullptr, const char source16=nullptr, const char source17=nullptr, const char source18=nullptr, const char source19=nullptr, const char source20=nullptr)
	Compiles a shader for a specific target. More...

void GEOGRAM_GFX_API	GEO::GLSL::link_program (GLuint program)
	Links a program. More...

GLuint GEOGRAM_GFX_API	GEO::GLSL::create_program_from_shaders_no_link (GLuint shader,...)
	Creates a GLSL program from a zero-terminated list of shaders. More...

GLuint GEOGRAM_GFX_API	GEO::GLSL::create_program_from_shaders (GLuint shader,...)
	Creates a GLSL program from a zero-terminated list of shaders. More...

GLuint GEOGRAM_GFX_API	GEO::GLSL::create_program_from_string_no_link (const char *string, bool copy_string=true)
	Creates a GLSL program from a string. More...

GLuint GEOGRAM_GFX_API	GEO::GLSL::create_program_from_file_no_link (const std::string &filename)
	Creates a GLSL program from a file. More...

template<class T >
bool	GEO::GLSL::set_program_uniform_by_name (GLuint shader_id, const char *name, T val)
	Sets a uniform variable in a shader by name. More...

template<>
bool	GEO::GLSL::set_program_uniform_by_name (GLuint shader_id, const char *name, bool val)

template<>
bool	GEO::GLSL::set_program_uniform_by_name (GLuint shader_id, const char *name, float val)

template<>
bool	GEO::GLSL::set_program_uniform_by_name (GLuint shader_id, const char *name, double val)

template<>
bool	GEO::GLSL::set_program_uniform_by_name (GLuint shader_id, const char *name, int val)

template<>
bool	GEO::GLSL::set_program_uniform_by_name (GLuint shader_id, const char *name, unsigned int val)

bool	GEO::GLSL::set_program_uniform_by_name (GLuint shader_id, const char name, index_t count, float values)
	Sets an array of uniform variables in a shader by name. More...

bool	GEO::GLSL::set_program_uniform_by_name (GLuint shader_id, const char *name, float x, float y)

GLint GEOGRAM_GFX_API	GEO::GLSL::get_uniform_variable_offset (GLuint program, const char *varname)
	Gets the offset of a uniform variable relative to the uniform block it is declared in. More...

size_t GEOGRAM_GFX_API	GEO::GLSL::get_uniform_variable_array_stride (GLuint program, const char *varname)
	Queries array stride for a variable in a GLSL program using introspection. More...

void GEOGRAM_GFX_API	GEO::GLSL::introspect_program (GLuint program)
	Outputs to the logger everything that can be queried about a program using OpenGL introspection APIs.

Detailed Description

Utilities for manipulating GLSL shaders.

Definition in file GLSL.h.

Typedef Documentation

◆ PseudoFile

typedef void(* GEO::GLSL::PseudoFile) (PseudoFileProvider *provider, std::vector< Source > &sources)

A pointer to a function registered as a pseudo file in the GLSL pseudo file system.

The GLSL pseudo file system manages the include directives. A PseudoFile is a pointer to a function that fills-in the file contents. The file contents is a vector of Source objects, that can be either constant string litterals or dynamically created strings.

Definition at line 192 of file GLSL.h.

Function Documentation

◆ compile_program_with_includes_no_link()

GLuint GEOGRAM_GFX_API GEO::GLSL::compile_program_with_includes_no_link	(	PseudoFileProvider *	provider,
		const char *	shader1,
		const char *	shader2 = `nullptr`,
		const char *	shader3 = `nullptr`,
		const char *	shader4 = `nullptr`,
		const char *	shader5 = `nullptr`,
		const char *	shader6 = `nullptr`
	)

Compiles a program from shader sources.

Parameters

[in]	provider	a pointer to an object that implements the PseudoFileProvider interface (typically a GLUP Context)
[in]	shader1,shader2,shader3,shader4,shader5,shader6	up to six shader sources definition. Each shader source definition should begin with //stage STAGE where STAGE is one of GL_VERTEX_SHADER, GL_FRAGMENT_SHADER, GL_GEOMETRY_SHADER, GL_TESSELLATION_SHADER, GL_TESS_EVALUATION_SHADER

Returns: the OpenGL opaque Id of the created program object

Exceptions

GLSLCompileError

◆ compile_shader() [1/2]

GLuint GEOGRAM_GFX_API GEO::GLSL::compile_shader	(	GLenum	target,
		const char **	sources,
		index_t	nb_sources
	)

Compiles a shader for a specific target.

One can split the source of the shader into different strings, one of them being used for library functions common to different shaders. It may seem more natural to generate a shader object with library functions, but OpenGL documentation does not recommend to do so (and it did not seem to work). Errors are detected and displayed to std::err.

Parameters

[in]	target	the OpenGL shader target (one of GL_COMPUTE_SHADER, GL_VERTEX_SHADER, GL_TESS_CONTROL_SHADER, GL_TESS_EVALUATION_SHADER, GL_GEOMETRY_SHADER, GL_FRAGMENT_SHADER)
[in]	sources	an array of pointer to ASCII strings that contain the source of the shader
[in]	nb_sources	number of strings in `sources`

Returns: the OpenGL opaque Id of the created shader object

Exceptions

GLSLCompileError

◆ compile_shader() [2/2]

GLuint GEOGRAM_GFX_API GEO::GLSL::compile_shader	(	GLenum	target,
		const char *	source1,
		const char *	source2,
		const char *	source3 = `nullptr`,
		const char *	source4 = `nullptr`,
		const char *	source5 = `nullptr`,
		const char *	source6 = `nullptr`,
		const char *	source7 = `nullptr`,
		const char *	source8 = `nullptr`,
		const char *	source9 = `nullptr`,
		const char *	source10 = `nullptr`,
		const char *	source11 = `nullptr`,
		const char *	source12 = `nullptr`,
		const char *	source13 = `nullptr`,
		const char *	source14 = `nullptr`,
		const char *	source15 = `nullptr`,
		const char *	source16 = `nullptr`,
		const char *	source17 = `nullptr`,
		const char *	source18 = `nullptr`,
		const char *	source19 = `nullptr`,
		const char *	source20 = `nullptr`
	)

Compiles a shader for a specific target.

One can split the source of the shader into different strings, one of them being used for library functions common to different shaders. It may seem more natural to generate a shader object with library functions, but OpenGL documentation does not recommend to do so (and it did not seem to work). Errors are detected and displayed to std::err.

Parameters

[in]	target	the OpenGL shader target (one of GL_COMPUTE_SHADER, GL_VERTEX_SHADER, GL_TESS_CONTROL_SHADER, GL_TESS_EVALUATION_SHADER, GL_GEOMETRY_SHADER, GL_FRAGMENT_SHADER)
[in]	source1,source2,...	ASCII strings that will be concatened to form the source of the shader. It needs to be terminated by 0.

Returns: the OpenGL opaque Id of the created shader object

Exceptions

GLSLCompileError

Note: Could have been implemented using varargs, but I had problems with it (crashes that I could not fix), and it is not recommended anyway (does not have typechecking).

◆ compile_shader_with_includes()

GLuint GEOGRAM_GFX_API GEO::GLSL::compile_shader_with_includes	(	GLenum	target,
		const char *	source,
		PseudoFileProvider *	provider
	)

Compiles a shader for a specific target.

This version of compile_shader() supports the include directive through the GLSL pseudo file system. Errors are detected and displayed to std::err.

Parameters

[in]	target	the OpenGL shader target (one of GL_COMPUTE_SHADER, GL_VERTEX_SHADER, GL_TESS_CONTROL_SHADER, GL_TESS_EVALUATION_SHADER, GL_GEOMETRY_SHADER, GL_FRAGMENT_SHADER)
[in]	source	an ASCII string that contain the source of the shader
[in]	provider	a pointer to an object that implements the PseudoFileProvider interface (typically a GLUP Context)

Returns: the OpenGL opaque Id of the created shader object

Exceptions

GLSLCompileError

◆ create_program_from_file_no_link()

GLuint GEOGRAM_GFX_API GEO::GLSL::create_program_from_file_no_link ( const std::string & filename )

Creates a GLSL program from a file.

The file contains a list of shaders, delimited by begin-end statements (see setup_program_from_string()).

Note: link_program() needs to be called after.

Parameters

[in] filename the name of the file

Exceptions

GLSLCompileError

◆ create_program_from_shaders()

GLuint GEOGRAM_GFX_API GEO::GLSL::create_program_from_shaders	(	GLuint	shader,
			...
	)

Creates a GLSL program from a zero-terminated list of shaders.

Errors are detected and displayed to the Logger.

Note: If the program has vertex attributes and needs glBindAttribLocation(), then use create_program_from_shaders_no_link() instead.

Parameters

[in] shader the first shader of the list

Returns: the OpenGL opaque Id of the created program

◆ create_program_from_shaders_no_link()

GLuint GEOGRAM_GFX_API GEO::GLSL::create_program_from_shaders_no_link	(	GLuint	shader,
			...
	)

Creates a GLSL program from a zero-terminated list of shaders.

Errors are detected and displayed to the Logger.

Note: link_program() needs to be called after. If the program has vertex attributes, then glBindAttribLocation() needs to be called after create_program_from_shaders_no_link() and before link_program().

Parameters

[in] shader the first shader of the list

Returns: the OpenGL opaque Id of the created program

◆ create_program_from_string_no_link()

GLuint GEOGRAM_GFX_API GEO::GLSL::create_program_from_string_no_link	(	const char *	string,
		bool	copy_string = `true`
	)

Creates a GLSL program from a string.

The string may contain several shaders. Each shader is delimited by begin-end statements: #begin(SHADER_TYPE) / #end(SHADER_TYPE) where SHADER_TYPE is one of GL_VERTEX_SHADER, GL_FRAGMENT_SHADER, GL_GEOMETRY_SHADER, GL_TESS_CONTROL_SHADER, GL_TESS_EVALUATION_SHADER.

Note: link_program() needs to be called after.

Parameters

[in,out]	string	the combined shaders that constitute the program.
[in]	copy_string	if true, the input string is copied internally. The function temporarily modifies the input string (and then restores it on exit). This may be forbidden when input string is a constant char array (string litteral in source code). In this case, the input string is copied to a temporary buffer.

Returns: the OpenGL opaque Id of the created shader object

Exceptions

GLSLCompileError

◆ get_GLSL_include_file()

const char* GEO::GLSL::get_GLSL_include_file ( const std::string & name )

Gets a GLSL include file by file name.

It needs to be a real file, registered as a pointer to static text data (not a PseudoFile).

Parameters

[in] name the name of the file in the pseudo file system.

Returns: a const pointer to the contents of the file.

◆ get_uniform_variable_array_stride()

size_t GEOGRAM_GFX_API GEO::GLSL::get_uniform_variable_array_stride	(	GLuint	program,
		const char *	varname
	)

Queries array stride for a variable in a GLSL program using introspection.

Parameters

[in]	program	the handle of the program
[in]	varname	a string with the name of the array variable

Returns: the number of bytes between two consecutive elements of the array.

◆ get_uniform_variable_offset()

GLint GEOGRAM_GFX_API GEO::GLSL::get_uniform_variable_offset	(	GLuint	program,
		const char *	varname
	)

Gets the offset of a uniform variable relative to the uniform block it is declared in.

Parameters

[in]	program	a GLSL program handle
[in]	varname	the name of the variable

Returns: the offset of the variable relative to the beginning of the uniform block it is declared in, in bytes.

◆ initialize()

void GEOGRAM_GFX_API GEO::GLSL::initialize ( )

Initializes some GLSL functions and objects.

Called by GEO::Graphics::initialize()

◆ link_program()

void GEOGRAM_GFX_API GEO::GLSL::link_program ( GLuint program )

Links a program.

Errors are detexted and displayed to the Logger.

Parameters

[in] program the program to be linked

◆ register_GLSL_include_file() [1/2]

void GEOGRAM_GFX_API GEO::GLSL::register_GLSL_include_file	(	const std::string &	name,
		const char *	source
	)

Registers a file in the GLSL pseudo file system.

The file can then be included in a GLSL source with the //include <name> directive.

Parameters

[in]	name	the name of the pseudo file
[in]	source	the GLSL source of the file

◆ register_GLSL_include_file() [2/2]

void GEOGRAM_GFX_API GEO::GLSL::register_GLSL_include_file	(	const std::string &	name,
		PseudoFile	file
	)

Registers a pseudo file in the GLSL pseudo file system.

The pseudo file can then be included in a GLSL source with the //include <name> directive. Each time it is included, it is generated by calling the specified function.

Parameters

[in]	name	the name of the pseudo file
[in]	file	a pointer to a member function of an object derived from a PseudoFileProvider object that returns a string.

◆ set_program_uniform_by_name() [1/2]

bool GEO::GLSL::set_program_uniform_by_name	(	GLuint	shader_id,
		const char *	name,
		index_t	count,
		float *	values
	)

inline

Sets an array of uniform variables in a shader by name.

Parameters

[in]	shader_id	the handle to the GLSL shader
[in]	name	the name of the uniform variable, as specified in the GLSL source of the shader.
[in]	count	number of values
[in]	values	a pointer to an array of values of size count

Definition at line 513 of file GLSL.h.

◆ set_program_uniform_by_name() [2/2]

template<class T >

bool GEO::GLSL::set_program_uniform_by_name	(	GLuint	shader_id,
		const char *	name,
		T	val
	)

inline

Sets a uniform variable in a shader by name.

Parameters

[in]	shader_id	the handle to the GLSL shader
[in]	name	the name of the uniform variable, as specified in the GLSL source of the shader.
[in]	val	the value of the parameter

Template Parameters

T	the type of the parameter. Needs to match the type of the uniform parameter in the GLSL source.

Definition at line 425 of file GLSL.h.

◆ supported_language_version()

double GEOGRAM_GFX_API GEO::GLSL::supported_language_version ( )

Gets the supported GLSL language version.

The supported GLSL version is determined from hardware/driver capabilities and user-defined parameters.

◆ terminate()

void GEOGRAM_GFX_API GEO::GLSL::terminate ( )

Terminates GLSL functions and objects.

Called by GEO::Graphics::terminate()

Classes

Namespaces

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ PseudoFile

Function Documentation

◆ compile_program_with_includes_no_link()

◆ compile_shader() [1/2]

◆ compile_shader() [2/2]

◆ compile_shader_with_includes()

◆ create_program_from_file_no_link()

◆ create_program_from_shaders()

◆ create_program_from_shaders_no_link()

◆ create_program_from_string_no_link()

◆ get_GLSL_include_file()

◆ get_uniform_variable_array_stride()

◆ get_uniform_variable_offset()

◆ initialize()

◆ link_program()

◆ register_GLSL_include_file() [1/2]

◆ register_GLSL_include_file() [2/2]

◆ set_program_uniform_by_name() [1/2]

◆ set_program_uniform_by_name() [2/2]

◆ supported_language_version()

◆ terminate()