OpenGL Shader Compilation. More...

#include <easy3d/renderer/shader_program.h>

Public Types
enum	AttribType { POSITION , COLOR , NORMAL , TEXCOORD }
	Types of vertex attributes. More...

enum	ShaderType { VERTEX , FRAGMENT , GEOMETRY , TESS_CONTROL , TESS_EVALUATION , COMPUTE , NUM_SHADER_TYPES }
	Types of Shaders. More...

typedef std::pair< AttribType, std::string >	Attribute
	Attribute: a pair of attribute type and attribute name.

Public Member Functions
	ShaderProgram (const std::string &name="unknown")

	~ShaderProgram ()
	Destructor.

void	set_name (const std::string &name)
	Set the name of the shader program.

const std::string &	name () const
	Get the name of the shader program.

void	set_verbose (bool v)
	Set verbose mode.

unsigned int	get_program () const
	Get the program index.

void	clear ()
	Remove (delete) all shaders.

bool	load_shader_from_file (ShaderType st, const std::string &file_name, const std::string &inc_id="#include")
	Load the text in the file to the source of the specified shader.

bool	load_shader_from_code (ShaderType st, const std::string &code)
	Load the code to the source of the specified shader.

void	set_attrib_name (ShaderProgram::AttribType at, const std::string &name) const
	Define semantics for the input vertex attributes. This is required for other libraries to know how to send data to the shader.

void	set_attrib_names (const std::vector< ShaderProgram::Attribute > &attributes) const
	Define semantics for multiple input vertex attributes.

bool	link_program ()
	Prepare program for usage. Links it and collects information about uniform variables and uniform blocks.

void	set_program_output (int index, const std::string &name) const
	Bind a user-defined varying out variable to a fragment shader color number.

int	program_output (const std::string &name) const
	Get the fragment shader color number bound to a user-defined varying out variable.

void	bind () const
	Start using the program.

ShaderProgram *	set_uniform (const std::string &name, const void *value)
	Set the uniform to value.

ShaderProgram *	set_uniform (const std::string &name, int value)
	Set the uniform to the int value.

ShaderProgram *	set_uniform (const std::string &name, unsigned int value)
	Set the uniform to the unsigned int value.

ShaderProgram *	set_uniform (const std::string &name, float value)
	Set the uniform to the float value.

ShaderProgram *	set_block (const std::string &name, const void *value)
	Set a uniform block as a whole.

ShaderProgram *	set_block_uniform (const std::string &blockName, const std::string &uniformName, const void *value)
	Set a uniform inside a named block.

ShaderProgram *	set_block_uniform_array_element (const std::string &blockName, const std::string &uniformName, int arrayIndex, const void *value)
	Set an element of an array of uniforms inside a block.

ShaderProgram *	bind_texture (const std::string &name, unsigned int tex_id, int unit, unsigned int tex_target=0x0DE1)
	Bind a texture to the shader program.

ShaderProgram *	release_texture (unsigned int tex_target=0x0DE1)
	Release a texture from the shader program.

void	release () const
	End using the program.

int	get_attribute_location (const std::string &name) const
	Get the location of an attribute.

bool	is_uniform_used (const std::string &name)
	Check if a uniform is used by the shader.

bool	is_attribute_used (const std::string &name)
	Check if an attribute is used by the shader.

bool	is_program_valid () const
	Check if the program is valid.

bool	is_program_linked () const
	Check if the program is linked.

bool	is_bound () const
	Check if the program is bound.

bool	shader_info_log (std::string &log, unsigned int shader) const
	Get the shader info log.

bool	program_info_log (std::string &log) const
	Get the program info log.

void	print_active_attributes ()
	Print active attributes.

void	print_active_uniforms ()
	Print active uniforms.

void	print_active_uniform_blocks ()
	Print active uniform blocks.

bool	load_binary (const std::string &file_name)
	Load a binary (i.e., compiled and linked) program.

bool	save_binary (const std::string &file_name)
	Save the program to a binary file.

Static Public Member Functions
static bool	is_supported ()
	Is shader program supported?

static std::string	load_shader_source (const std::string &file_name, const std::string &inc_id="#include")
	Auxiliary function that loads the shader source code from a file.

Friends
class	ShaderManager

Detailed Description

OpenGL Shader Compilation.

This class allows to create programs, load shaders from files, associate vertex attribute names with locations, and work with uniforms, including blocks. It also provides access to the info logs, and many more useful functionalities. To use the shader program class, you need to do the following:

Call load_shader_from_code(ShaderProgram::VERTEX, vert_file) to create vertex shader and load_shader_from_code(ShaderProgram::FRAGMENT, frag_file) to create fragment shader (you may also need to create other types of shaders depending on your needs).
Call set_attrib_name(ShaderProgram::POSITION, "position") for vertex attribute "position". You may also need to set other attributes like normal, color, etc. To know what vertex attributes need to be set, check your shader code or call print_active_attributes().
Call link_program() to link the program.

For rendering

Call bind();
Call set_uniform() to set all the necessary uniforms. You may also need to call set_block(), set_block_uniform(), and/or set_block_uniform_array_element(). To know what uniforms need to be set, check your shader code or call print_active_uniforms(), print_active_uniform_blocks().
Call the drawable's draw() function
Call release();

To retrieve the model view projection matrix, call camera's modelViewProjectionMatrix()

Examples: Tutorial_207_RealCamera/main.cpp, Tutorial_501_AmbientOcclusion/main.cpp, Tutorial_505_EyeDomeLighting/main.cpp, and Tutorial_506_DepthMap/main.cpp.

Member Enumeration Documentation

◆ AttribType

enum AttribType

Types of vertex attributes.

Enumerator
POSITION	Position.
COLOR	Color.
NORMAL	Normal.
TEXCOORD	Texture coordinates.

◆ ShaderType

enum ShaderType

Types of Shaders.

Enumerator
VERTEX	Vertex shader.
FRAGMENT	Fragment shader.
GEOMETRY	Geometry shader.
TESS_CONTROL	Tessellation control shader.
TESS_EVALUATION	Tessellation evaluation shader.
COMPUTE	Compute shader.
NUM_SHADER_TYPES	Number of shader types.

Constructor & Destructor Documentation

◆ ShaderProgram()

ShaderProgram ( const std::string & name = "unknown" )

explicit

Constructor.

Parameters

name	A unique name for a program, convenient to distinguish multiple programs. This is quite helpful in identifying issues when multiple programs are used. It is suggested to use the source file name.

Member Function Documentation

◆ bind_texture()

ShaderProgram * bind_texture	(	const std::string &	name,
		unsigned int	tex_id,
		int	unit,
		unsigned int	tex_target = 0x0DE1 )

Bind a texture to the shader program.

Parameters

name	The name of the texture.
tex_id	The texture ID.
unit	The texture unit.
tex_target	The texture target, which can be GL_TEXTURE_2D (default), GL_TEXTURE_2D_MULTISAMPLE, or GL_TEXTURE_2D_ARRAY.

Returns: A pointer to the ShaderProgram object.

Examples: Tutorial_501_AmbientOcclusion/main.cpp.

◆ get_attribute_location()

int get_attribute_location ( const std::string & name ) const

Get the location of an attribute.

Parameters

name	The name of the attribute.

Returns: The location of the attribute.

◆ get_program()

unsigned int get_program ( ) const

Get the program index.

Returns: The program index.

◆ is_attribute_used()

bool is_attribute_used ( const std::string & name )

Check if an attribute is used by the shader.

Parameters

name	The name of the attribute.

Returns: True if the attribute is used, false otherwise.

◆ is_bound()

bool is_bound ( ) const

Check if the program is bound.

Returns: True if the program is bound (i.e., between bind() and release()), false otherwise.

◆ is_program_linked()

bool is_program_linked ( ) const

Check if the program is linked.

Returns: True if the program is linked, false otherwise.

◆ is_program_valid()

bool is_program_valid ( ) const

Check if the program is valid.

Returns: True if the program is valid, false otherwise.

Note: glValidateProgram() is meant to be called directly before a draw call (i.e., glDraw*()) with that shader bound and all the bindings (VAO, textures) set. Its purpose is to ensure that the shader can execute given the current GL state.

◆ is_supported()

bool is_supported ( )

static

Is shader program supported?

Returns: true if supported, false otherwise.

◆ is_uniform_used()

bool is_uniform_used ( const std::string & name )

Check if a uniform is used by the shader.

This can save some compute time if the uniforms or attributes are expensive to compute.

Parameters

name	The name of the uniform.

Returns: True if the uniform is used, false otherwise.

Note: The program must be compiled and linked.

◆ link_program()

bool link_program ( )

Prepare program for usage. Links it and collects information about uniform variables and uniform blocks.

Returns: True if the program was linked successfully, false otherwise.

◆ load_binary()

bool load_binary ( const std::string & file_name )

Load a binary (i.e., compiled and linked) program.

Parameters

file_name The name of the file to load the binary from.

Returns: True if the binary was loaded successfully, false otherwise.

Note: Requires OpenGL >= 4.1.

◆ load_shader_from_code()

bool load_shader_from_code	(	ShaderType	st,
		const std::string &	code )

Load the code to the source of the specified shader.

Parameters

st	One of the enum values of ShaderType.
code	The string of the shader source code.

Returns: True if the shader was loaded successfully, false otherwise.

◆ load_shader_from_file()

bool load_shader_from_file	(	ShaderType	st,
		const std::string &	file_name,
		const std::string &	inc_id = "#include" )

Load the text in the file to the source of the specified shader.

Parameters

st	One of the enum values of ShaderType.
file_name	The full path of the file where the source is to be found.
inc_id	The include identifier string (e.g., "#include").

Returns: True if the shader was loaded successfully, false otherwise.

◆ load_shader_source()

std::string load_shader_source	(	const std::string &	file_name,
		const std::string &	inc_id = "#include" )

static

Auxiliary function that loads the shader source code from a file.

Parameters

file_name	The full path of the file where the source is to be found.
inc_id	The include identifier string (e.g., "#include").

Returns: The shader source code as a string.

◆ name()

const std::string & name ( ) const

inline

Get the name of the shader program.

Returns: The name of the shader program.

◆ print_active_attributes()

void print_active_attributes ( )

Print active attributes.

Note: Requires OpenGL >= 4.3.

◆ print_active_uniform_blocks()

void print_active_uniform_blocks ( )

Print active uniform blocks.

Note: Requires OpenGL >= 4.3.

◆ print_active_uniforms()

void print_active_uniforms ( )

Print active uniforms.

Note: Requires OpenGL >= 4.3.

◆ program_info_log()

bool program_info_log ( std::string & log ) const

Get the program info log.

returns a string with the program's infolog

Parameters

log	The string to store the program's info log.

Returns: True if program linkage was successfully, false otherwise.

◆ program_output()

int program_output ( const std::string & name ) const

Get the fragment shader color number bound to a user-defined varying out variable.

Note: Linking is required for this operation to take effect (call method prepare_program afterward).

Parameters

name	The name of the fragment's shader variable.

Returns: The fragment color number.

◆ release_texture()

ShaderProgram * release_texture ( unsigned int tex_target = 0x0DE1 )

Release a texture from the shader program.

Parameters

tex_target The texture target (default is GL_TEXTURE_2D).

Returns: A pointer to the ShaderProgram object.

Examples: Tutorial_501_AmbientOcclusion/main.cpp.

◆ save_binary()

bool save_binary ( const std::string & file_name )

Save the program to a binary file.

Parameters

file_name The name of the file to save the binary to.

Returns: True if the binary was saved successfully, false otherwise.

Note: Requires OpenGL >= 4.1.

◆ set_attrib_name()

void set_attrib_name	(	ShaderProgram::AttribType	at,
		const std::string &	name ) const

Define semantics for the input vertex attributes. This is required for other libraries to know how to send data to the shader.

Parameters

at	The semantic of the attribute.
name	The name of the vertex attribute.

Note: To specify a location for an attribute you must do it prior to linking the program, or, if the program is already linked, to link it again afterward (call method link_program).

◆ set_attrib_names()

void set_attrib_names ( const std::vector< ShaderProgram::Attribute > & attributes ) const

Define semantics for multiple input vertex attributes.

Parameters

attributes A vector of attributes to set.

◆ set_block()

ShaderProgram * set_block	(	const std::string &	name,
		const void *	value )

Set a uniform block as a whole.

Parameters

name	The name of the uniform block.
value	The value to set.

Returns: A pointer to the ShaderProgram object.

◆ set_block_uniform()

ShaderProgram * set_block_uniform	(	const std::string &	blockName,
		const std::string &	uniformName,
		const void *	value )

Set a uniform inside a named block.

Parameters

blockName	The name of the uniform block.
uniformName	The name of the uniform.
value	The value to set.

Returns: A pointer to the ShaderProgram object.

Warning: Be careful when using uniform blocks. Please refer to OpenGL Specification Version 4.5 (Core Profile) - May 28, 2015 (https://www.opengl.org/registry/doc/glspec45.core.pdf#page=159) In "Standard Uniform Block Layout", it says "If the member is a three-component vector with components consuming N basic machine units, the base alignment is 4N" (see rule 3 of section 7.6.2.2 in page.159). That means the array stride (the bytes between array elements) is always rounded up to the size of a vec4 (i.e., 16-bytes). So we have to avoid using vec3/mat3 (use vec4/mat4/mat43 instead) in a uniform block. Otherwise, you have to manually pad your structures/arrays out.

Examples: Tutorial_501_AmbientOcclusion/main.cpp.

◆ set_block_uniform_array_element()

ShaderProgram * set_block_uniform_array_element	(	const std::string &	blockName,
		const std::string &	uniformName,
		int	arrayIndex,
		const void *	value )

Set an element of an array of uniforms inside a block.

Parameters

blockName	The name of the uniform block.
uniformName	The name of the uniform.
arrayIndex	The index of the array element.
value	The value to set.

Returns: A pointer to the ShaderProgram object.

◆ set_name()

void set_name ( const std::string & name )

inline

Set the name of the shader program.

Parameters

name	The name to set.

◆ set_program_output()

void set_program_output	(	int	index,
		const std::string &	name ) const

Bind a user-defined varying out variable to a fragment shader color number.

Note: Linking is required for this operation to take effect (call method prepare_program afterward).

Parameters

index	The fragment color number.
name	The name of the fragment's shader variable.

◆ set_uniform() [1/4]

ShaderProgram * set_uniform	(	const std::string &	name,
		const void *	value )

Set the uniform to value.

Parameters

name	The name of the uniform.
value	The value to set.

Returns: A pointer to the ShaderProgram object.

Note: If your uniform is an array type, be careful to use the correct uniform names. For example, you have 'uniform vec2/float values[8]' in your shader code, the uniform name is 'values[0]' (not 'values'). So calling to this function looks like: program->set_uniform("values[0]", valueArray);

Examples: Tutorial_207_RealCamera/main.cpp, Tutorial_501_AmbientOcclusion/main.cpp, Tutorial_505_EyeDomeLighting/main.cpp, and Tutorial_506_DepthMap/main.cpp.

◆ set_uniform() [2/4]

ShaderProgram * set_uniform	(	const std::string &	name,
		float	value )

Set the uniform to the float value.

Parameters

name	The name of the uniform.
value	The float value to set.

Returns: A pointer to the ShaderProgram object.

◆ set_uniform() [3/4]

ShaderProgram * set_uniform	(	const std::string &	name,
		int	value )

Set the uniform to the int value.

Parameters

name	The name of the uniform.
value	The int value to set.

Returns: A pointer to the ShaderProgram object.

◆ set_uniform() [4/4]

ShaderProgram * set_uniform	(	const std::string &	name,
		unsigned int	value )

Set the uniform to the unsigned int value.

Parameters

name	The name of the uniform.
value	The unsigned int value to set.

Returns: A pointer to the ShaderProgram object.

◆ set_verbose()

void set_verbose ( bool v )

inline

Set verbose mode.

Parameters

v	True to enable verbose mode (log any issues found), false to disable.

◆ shader_info_log()

bool shader_info_log	(	std::string &	log,
		unsigned int	shader ) const

Get the shader info log.

returns a string with a shader's infolog

Parameters

log	The string to store the shader's info log.
shader	The shader ID.

Returns: True if shader compilation was successfully, false otherwise.

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

G:/3_code/Easy3D/easy3d/renderer/shader_program.h
G:/3_code/Easy3D/easy3d/renderer/shader_program.cpp

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ AttribType

◆ ShaderType

Constructor & Destructor Documentation

◆ ShaderProgram()

Member Function Documentation

◆ bind_texture()

◆ get_attribute_location()

◆ get_program()

◆ is_attribute_used()

◆ is_bound()

◆ is_program_linked()

◆ is_program_valid()

◆ is_supported()

◆ is_uniform_used()

◆ link_program()

◆ load_binary()

◆ load_shader_from_code()

◆ load_shader_from_file()

◆ load_shader_source()

◆ name()

◆ print_active_attributes()

◆ print_active_uniform_blocks()

◆ print_active_uniforms()

◆ program_info_log()

◆ program_output()

◆ release_texture()

◆ save_binary()

◆ set_attrib_name()

◆ set_attrib_names()

◆ set_block()

◆ set_block_uniform()

◆ set_block_uniform_array_element()

◆ set_name()

◆ set_program_output()

◆ set_uniform() [1/4]

◆ set_uniform() [2/4]

◆ set_uniform() [3/4]

◆ set_uniform() [4/4]

◆ set_verbose()

◆ shader_info_log()