cgv::render::texture Class Reference

#include <texture.h>

Inheritance diagram for cgv::render::texture:

Public Member Functions
virtual bool	is_created () const
	return whether component has been created
void	put_id_void (void *ptr) const
template<typename T >
void	put_id (T &id) const
	cast the refence to rendering api specific representation of component id to the specified type
void	set_dimensions (unsigned _d0, unsigned _d1=-1, unsigned _d2=-1, unsigned _d3=-1)
	set the dimensions to the given values
unsigned int	get_nr_dimensions () const
	return the number of dimensions of the data set More...
void	set_nr_dimensions (unsigned int _d)
	set the number of dimensions of the data set More...
unsigned int	get_resolution (unsigned int i) const
	return the resolution in the i-th dimension, or 0 if not defined More...
unsigned int	get_width () const
	return the resolution in the first dimension, or 1 if not defined More...
unsigned int	get_height () const
	return the resolution in the second dimension, or 1 if not defined More...
unsigned int	get_depth () const
	return the resolution in the third dimension, or 1 if not defined More...
unsigned int	get_nr_time_steps () const
	return the resolution in the highest dimension, or 1 if not defined More...
size_t	get_nr_entries () const
	return the total number of data entries
size_t	get_nr_bytes () const
	return the total number of bytes necessary to store the data
void	set_resolution (unsigned int i, unsigned int resolution)
	set the resolution in the i-th dimension, add dimensions if necessary More...
void	set_width (unsigned int _width)
	set the resolution in the first dimension, add dimensions if necessary More...
void	set_height (unsigned int _height)
	set the resolution in the second dimension, add dimensions if necessary More...
void	set_depth (unsigned int _depth)
	set the resolution in the third dimension, add dimensions if necessary More...
void	set_nr_time_steps (unsigned int _nr_time_steps)
	set the resolution in the last dimension, add dimensions if necessary More...
unsigned int	get_entry_alignment () const
	return the alignment of entries
unsigned int	get_alignment (unsigned int i) const
	return the alignment of a given dimension More...
void	set_entry_alignment (unsigned int _a)
	set the alignment of entries
void	set_alignment (unsigned int i, unsigned int _a)
	set the alignment of a given dimension More...
unsigned int	get_layout_dimension (unsigned int dim) const
	return the layout dimension of a given dimension
void	get_layout_dimension (unsigned int dim, unsigned int layout_dim)
	set the layout dimension of a given dimension, add dimensions if necessary More...
const component_format &	get_component_format () const
	return the component_format info by simple conversion of the this pointer
void	set_component_format (const component_format &cf)
	set component_format by simply assigning to a converted this pointer
void	set_component_format (ComponentFormat _cf)
	set the component names from a standard component format More...
bool	operator== (const data_format &df) const
	comparison between component formats
bool	operator== (const component_format &cf) const
	comparison between component formats
bool	operator== (const packing_info &pi) const
	equal comparison
bool	operator!= (const data_format &df) const
	comparison between component formats
bool	operator!= (const component_format &cf) const
	comparison between component formats
bool	operator!= (const packing_info &pi) const
	unequal comparison
void	set_components (const std::string &_components)
	comma separated list of component descriptors, for example "R,G,B"
void	set_integer_interpretation (ComponentIntegerInterpretation cii)
	set the integer interpretation
ComponentIntegerInterpretation	get_integer_interpretation () const
	return current integer interpretation
template<typename T >
T	get (int ci, const void *ptr) const
	constant access to the i-th component stored at the given location
template<typename T >
bool	set (int ci, void *ptr, const T &v) const
	write access to the i-th component, return whether write was successful
bool	empty () const
	return whether the component format is defined
void	clear ()
	clear the component format
const packing_info &	get_packing_info () const
	return the packing info by simple conversion of the this pointer
void	set_packing_info (const packing_info &pi)
	set packing info by simply assigning to a converted this pointer
unsigned int	get_nr_components () const
	return the number of components More...
unsigned int	get_component_index (const std::string &name) const
	return the index of a component given by name or -1 if not found
std::string	get_component_name (unsigned int i) const
	return the name of the component with index i
ComponentFormat	get_standard_component_format () const
	return whether the component format is one of the standard formats
void	set_component_names (const std::string &_component_name_list)
	set component names from a comma or colon separated list of names
TypeId	get_component_type () const
	return the component type
void	set_component_type (TypeId _type_id)
	set the component type
unsigned int	get_entry_size () const
	return the size of one entry of components in bytes More...
unsigned int	get_bit_depth (unsigned int ci) const
	return the bit depth of the ci-th component
void	set_bit_depth (unsigned int ci, unsigned int depth)
	set the bit depth of the ci-th component
bool	is_packing () const
	return whether packing is enabled
void	set_packing (bool enable=true)
	set the packing flag
unsigned int	get_component_alignment () const
	return the component alignment in bits in the packed case and in bytes in the unpacked case
void	set_component_alignment (unsigned int a)
	set the component alignment in bits in the packed case and in bytes in the unpacked case
int	get_signed (unsigned int ci, const void *ptr) const
	return the ci-th component of the data entry pointed to by the given pointer of a signed packed component
unsigned int	get_unsigned (unsigned int ci, const void *ptr) const
	return the ci-th component of the data entry pointed to by the given pointer of an unsigned packed component
bool	set_signed (unsigned int ci, void *ptr, int v) const
	set the ci-th component of the data entry pointed to by the given pointer of a signed packed component
bool	set_unsigned (unsigned int ci, void *ptr, unsigned int v) const
	set the ci-th component of the data entry pointed to by the given pointer of an unsigned packed component
methods that can be called without context
	texture (const std::string &description="uint8[R,G,B,A]", TextureFilter _mag_filter=TF_LINEAR, TextureFilter _min_filter=TF_LINEAR, TextureWrap _wrap_s=TW_CLAMP_TO_EDGE, TextureWrap _wrap_t=TW_CLAMP_TO_EDGE, TextureWrap _wrap_r=TW_CLAMP_TO_EDGE)
	~texture ()
bool	set_data_format (const std::string &description)
	change the data format and clear internal format
void	set_component_format (const component_format &cf)
	change component format and clear internal format
void	set_component_format (const std::string &description)
	change component format and clear internal format
void	set_wrap_s (TextureWrap _wrap_s)
	set the texture wrap behaviour in s direction
void	set_wrap_t (TextureWrap _wrap_t)
	set the texture wrap behaviour in t direction
void	set_wrap_r (TextureWrap _wrap_r)
	set the texture wrap behaviour in r direction
TextureWrap	get_wrap_s () const
	return the texture wrap behaviour in s direction
TextureWrap	get_wrap_t () const
	return the texture wrap behaviour in t direction
TextureWrap	get_wrap_r () const
	return the texture wrap behaviour in r direction
void	set_border_color (const float *rgba)
	set the border color
void	set_border_color (float r, float g, float b, float a=1.0f)
	set the border color
void	set_min_filter (TextureFilter _min_filter, float _anisotropy=2.0f)
TextureFilter	get_min_filter () const
	return the minification filter
float	get_anisotropy () const
	return the currently set anisotropy
void	set_mag_filter (TextureFilter _mag_filter)
	set the magnification filter
TextureFilter	get_mag_filter () const
	return the magnification filter
void	set_priority (float _priority)
	set priority with which texture is kept in GPU memory
float	get_priority () const
	return the priority with which texture is kept in GPU memory
void	set_compare_mode (bool use_compare_function)
	set the texture compare mode and function
bool	get_compare_mode () const
	get the texture compare mode and function
void	set_compare_function (CompareFunction compare_function)
	set the texture compare function
CompareFunction	get_compare_function () const
	get the texture compare function
bool	mipmaps_created () const
	check whether mipmaps have been created
void	ensure_state (const context &ctx) const
	ensure the the texture state is synchronized with the GPU settings
bool	is_enabled () const
	check whether textue is enabled
int	get_tex_unit () const
	return the currently used texture unit and -1 for current
methods that change the current gpu context
bool	enable (const context &ctx, int tex_unit=-1)
bool	disable (const context &ctx)
	disable texture and restore state before last enable call

Static Public Member Functions
static const std::string &	get_last_error ()
	returns an error string after parsing of description string has failed
static unsigned int	align (unsigned int v, unsigned int a)
	return the next integer larger or equal to v which is dividable by a

Public Attributes
std::string	last_error
	a string that contains the last error
const context *	ctx_ptr
	keep pointer to my context

Protected Member Functions
void	extract_components ()
	extract components from component string More...
methods that can be called only with a context
bool	complete_create (const context &ctx, bool created)

Protected Attributes
std::vector< dimension_info >	dimensions
	store for each dimension resolution and alignment in a dimension_info struct
TypeId	component_type
	store the type id of the component type
ComponentIntegerInterpretation	component_interpretation
	interpretation of integer typed components
std::string	component_string
	store all component names in one string separated with 0-chars
std::vector< unsigned short >	component_positions
	store the position of each component in the component string

methods that can be called only with a context
void	find_best_format (const context &ctx, const std::vector< cgv::data::data_view > *palettes=0)
	find the format that matches the one specified in the component format best
bool	create (const context &ctx, TextureType _tt=TT_UNDEF, unsigned width=-1, unsigned height=-1, unsigned depth=-1)
bool	create_from_image (const context &ctx, const std::string &file_name="", int *image_width_ptr=0, int *image_height_ptr=0, unsigned char *clear_color_ptr=0, int level=-1, int cube_side=-1)
bool	create_from_image (cgv::data::data_format &df, cgv::data::data_view &dv, const context &ctx, const std::string &file_name="", unsigned char *clear_color_ptr=0, int level=-1, int cube_side=-1)
bool	create_from_images (const context &ctx, const std::string &file_names, int level=-1)
	Create a cube map from six files specified in the file_names parameter. More...
bool	write_to_file (context &ctx, const std::string &file_name, unsigned int z_or_cube_side=-1, float depth_map_gamma=1.0f) const
	write the content of the texture to a file. This method needs support for frame buffer objects.
bool	generate_mipmaps (const context &ctx)
bool	create_from_buffer (const context &ctx, int x, int y, int width, int height, int level=-1)
bool	create (const context &ctx, const cgv::data::const_data_view &data, int level=-1, int cube_side=-1, int num_array_layers=0, const std::vector< cgv::data::data_view > *palettes=0)
bool	replace (const context &ctx, int x, const cgv::data::const_data_view &data, int level=-1, const std::vector< cgv::data::data_view > *palettes=0)
bool	replace (const context &ctx, int x, int y, const cgv::data::const_data_view &data, int level=-1, const std::vector< cgv::data::data_view > *palettes=0)
bool	replace (const context &ctx, int x, int y, int z_or_cube_side, const cgv::data::const_data_view &data, int level=-1, const std::vector< cgv::data::data_view > *palettes=0)
bool	replace_from_buffer (const context &ctx, int x, int y, int x_buffer, int y_buffer, int width, int height, int level=-1)
	replace a block within a 2d texture from the current read buffer.
bool	replace_from_buffer (const context &ctx, int x, int y, int z_or_cube_side, int x_buffer, int y_buffer, int width, int height, int level)
	replace a block within a 3d texture or a side from a cube map from the current read buffer. More...
bool	replace_from_image (const context &ctx, const std::string &file_name, int x, int y, int z_or_cube_side, int level)
	replace within a slice of a volume or a side of a cube map from the given image
bool	replace_from_image (cgv::data::data_format &df, cgv::data::data_view &dv, const context &ctx, const std::string &file_name, int x, int y, int z_or_cube_side, int level)
bool	destruct (const context &ctx)
	destruct the texture and free texture memory and handle
static bool	deduce_file_names (const std::string &file_names, std::vector< std::string > &deduced_names)
	Helper function that determins the individual file names for a cubemap. More...

Detailed Description

the texture class encapsulates all functionality independent of the rendering api.

Constructor & Destructor Documentation

texture()

cgv::render::texture::texture	(	const std::string &	description = "uint8[R,G,B,A]",
		TextureFilter	_mag_filter = TF_LINEAR,
		TextureFilter	_min_filter = TF_LINEAR,
		TextureWrap	_wrap_s = TW_CLAMP_TO_EDGE,
		TextureWrap	_wrap_t = TW_CLAMP_TO_EDGE,
		TextureWrap	_wrap_r = TW_CLAMP_TO_EDGE
	)

construct from description string (which defaults to rgba format) and most commonly used texture parameters. The description can define a component format as described in cgv::data::component_format::set_component_format() or a data format as described in cgv::data::data_format::set_data_format().

construct from description string and most commonly used texture parameters. The description can define a component format as described in cgv::data::component_format::set_component_format() or a data format as described in cgv::data::data_format::set_data_format().

~texture()

cgv::render::texture::~texture

(

)

destruct texture, the destructor can be called without context if the destruct method has been called or no creation has taken place

Member Function Documentation

create() [1/2]

bool cgv::render::texture::create	(	const context &	ctx,
		const cgv::data::const_data_view &	data,
		int	level = -1,
		int	cube_side = -1,
		int	num_array_layers = 0,
		const std::vector< cgv::data::data_view > *	palettes = 0
	)

create texture from data view. Use dimension and resolution of data view but the component format of the texture. If level is not specified or set to -1 mipmaps are generated. If cube_side is specified, and data view is 2D, create one of the six sides of a cubemap. If num_array_layers is not zero a texture array is created. Set num_array_layers to -1 to automatically choose the layer number based on the data view dimensions and size, e.g. a 2D/3D data view creates a 1D/2D array with layer count equal to height/depth. Set num_array_layers to > 0 to manually specify the layer count. This can be used to create a one layer 1D/2D texture array from a 1D/2D data view. Cubemap arrays are currently not suported.

create() [2/2]

bool cgv::render::texture::create	(	const context &	ctx,
		TextureType	_tt = TT_UNDEF,
		unsigned	width = -1,
		unsigned	height = -1,
		unsigned	depth = -1
	)

create the texture of dimension and resolution specified in the data format base class. If no type is given, determine it from the format. If dimensions are given, they overwrite the dimensions in the texture format.

create the texture of dimension and resolution specified in the data format base class

create_from_buffer()

bool cgv::render::texture::create_from_buffer	(	const context &	ctx,
		int	x,
		int	y,
		int	width,
		int	height,
		int	level = -1
	)

create texture from the currently set read buffer, where x, y, width and height define the to be used rectangle of the read buffer. The dimension and resolution of the texture format are updated automatically. If level is not specified or set to -1 mipmaps are generated.

create_from_image() [1/2]

bool cgv::render::texture::create_from_image	(	cgv::data::data_format &	df,
		cgv::data::data_view &	dv,
		const context &	ctx,
		const std::string &	file_name = "",
		unsigned char *	clear_color_ptr = 0,
		int	level = -1,
		int	cube_side = -1
	)

same as previous method but use the passed data format and data view to store the content of the image. No pointers to width and height can be passed as this information is available in the data_format after the call.

create_from_image() [2/2]

bool cgv::render::texture::create_from_image	(	const context &	ctx,
		const std::string &	file_name = "",
		int *	image_width_ptr = 0,
		int *	image_height_ptr = 0,
		unsigned char *	clear_color_ptr = 0,
		int	level = -1,
		int	cube_side = -1
	)

create the texture from an image file. If the file_name is not given ask the user interactively for a file name. The image dimensions are written to the optionally passed pointers image_width_ptr and image_height_ptr. In order to support mipmapping, the width and height of the texture must be powers of two. If the clear_color_ptr is given, the texture is automatically extended in size to powers of two. clear_color_ptr points to four bytes that specify a RGBA color used to fill texels that are inserted to ensure dimensions of powers of two. For creation of a side of a cubemap specify the cube_side parameter.

create the texture from an image file

create_from_images()

bool cgv::render::texture::create_from_images	(	const context &	ctx,
		const std::string &	file_names,
		int	level = -1
	)

Create a cube map from six files specified in the file_names parameter.

The file_names parameter can specify different file names by the use of the wildchar symbol '*' or by curly brackets. When using '*' the files are loaded in alphanumerical order. The image files defining the cubemap sides must be in the order positive x, negative x, positive y, negative y, positive z and negative z. Some examples of specifying file names:

• "cm_{xp,xn,yp,yn,zp,zn}.png" defines the file names "cm_xp.png", "cm_xn.png", "cm_yp.png", "cm_yn.png", "cm_zp.png" and "cm_zn.png"

"cm_*.png" issues a glob command resulting in an alphanumerically ordered file name list. Be aware that the naming of the previous example would result in a wrong ordering of the file names. Mixing of '*' and "{,}" syntax is not allowed. The static method deduce_file_names is used to deduce the individual file names from the file_names parameter and can be used also when the correct path to the cubemap files needs to be found.

Different levels of the mipmap pyramid can be created in separate calls. If the level parameter is not specified or -1, the images are load to level 0 and a mipmap pyramid is built automatically. This method has no support for rescaling to power of two dimensions. If a mipmap is used, the image files should already have power of two dimensions.

deduce_file_names()

bool cgv::render::texture::deduce_file_names ( const std::string &  file_names, std::vector< std::string > &  deduced_names  )

static

Helper function that determins the individual file names for a cubemap.

Returns whether the file_names specification was correct. See comment to create_from_images for the syntax of the file_names parameter.

enable()

bool cgv::render::texture::enable	(	const context &	ctx,
		int	_tex_unit = -1
	)

enable this texture in the given texture unit, -1 corresponds to the current unit.

extract_components()

void cgv::data::component_format::extract_components ( )

protectedinherited

extract components from component string

extract component_positions from component string

generate_mipmaps()

bool cgv::render::texture::generate_mipmaps

(

const context &

ctx

)

generate mipmaps automatically, only supported if framebuffer objects are supported by the GPU

get_alignment()

unsigned int cgv::data::data_format::get_alignment ( unsigned int  i ) const

inherited

return the alignment of a given dimension

return the alignment of a given dimension, where the alignment of the last dimension is always 1 and cannot be changed. This method also returns 1 if i is out of the range of valid dimensions.

get_depth()

unsigned int cgv::data::data_format::get_depth ( ) const

inherited

return the resolution in the third dimension, or 1 if not defined

return the number of entries in the third dimension

get_entry_size()

unsigned int cgv::data::component_format::get_entry_size ( ) const

inherited

return the size of one entry of components in bytes

return the size of one entry of component_positions in bytes

get_height()

unsigned int cgv::data::data_format::get_height ( ) const

inherited

return the resolution in the second dimension, or 1 if not defined

return the number of entries in the second dimension

get_layout_dimension()

void cgv::data::data_format::get_layout_dimension ( unsigned int  dim, unsigned int  layout_dim  )

inherited

set the layout dimension of a given dimension, add dimensions if necessary

set the layout dimension of a given dimension

get_nr_components()

unsigned int cgv::data::component_format::get_nr_components ( ) const

inherited

return the number of components

return the number of component_positions

get_nr_dimensions()

unsigned int cgv::data::data_format::get_nr_dimensions ( ) const

inherited

return the number of dimensions of the data set

return the dimension of the data set

get_nr_time_steps()

unsigned int cgv::data::data_format::get_nr_time_steps ( ) const

inherited

return the resolution in the highest dimension, or 1 if not defined

return the number of entries in the last dimension

get_resolution()

unsigned int cgv::data::data_format::get_resolution ( unsigned int  i ) const

inherited

return the resolution in the i-th dimension, or 0 if not defined

return the number of data entries in the given dimension

get_width()

unsigned int cgv::data::data_format::get_width ( ) const

inherited

return the resolution in the first dimension, or 1 if not defined

return the number of entries in the first dimension

put_id_void()

void cgv::render::render_component::put_id_void ( void *  ptr ) const

inherited

copy the rendering api specific id the component to the memory location of the given pointer. For opengl this the passed pointer should be of type GLint or GLuint.

replace() [1/3]

bool cgv::render::texture::replace	(	const context &	ctx,
		int	x,
		const cgv::data::const_data_view &	data,
		int	level = -1,
		const std::vector< cgv::data::data_view > *	palettes = 0
	)

replace a block within a 1d texture with the given data. If level is not specified, level 0 is set and if a mipmap has been created before, coarser levels are updated also.

replace() [2/3]

bool cgv::render::texture::replace	(	const context &	ctx,
		int	x,
		int	y,
		const cgv::data::const_data_view &	data,
		int	level = -1,
		const std::vector< cgv::data::data_view > *	palettes = 0
	)

replace a block within a 2d texture with the given data. If level is not specified, level 0 is set and if a mipmap has been created before, coarser levels are updated also.

replace() [3/3]

bool cgv::render::texture::replace	(	const context &	ctx,
		int	x,
		int	y,
		int	z_or_cube_side,
		const cgv::data::const_data_view &	data,
		int	level = -1,
		const std::vector< cgv::data::data_view > *	palettes = 0
	)

replace a block within a 3d texture or a side of a cube map with the given data. If level is not specified, level 0 is set and if a mipmap has been created before, coarser levels are updated also.

replace_from_buffer()

bool cgv::render::texture::replace_from_buffer	(	const context &	ctx,
		int	x,
		int	y,
		int	z_or_cube_side,
		int	x_buffer,
		int	y_buffer,
		int	width,
		int	height,
		int	level
	)

replace a block within a 3d texture or a side from a cube map from the current read buffer.

replace a block within a 2d texture from the current read buffer.

replace_from_image()

bool cgv::render::texture::replace_from_image	(	cgv::data::data_format &	df,
		cgv::data::data_view &	dv,
		const context &	ctx,
		const std::string &	file_name,
		int	x,
		int	y,
		int	z_or_cube_side,
		int	level
	)

same as previous method but use the passed data format and data view to store the content of the image.

set_alignment()

void cgv::data::data_format::set_alignment ( unsigned int  i, unsigned int  _a  )

inherited

set the alignment of a given dimension

set the alignment of a given dimension, add dimensions if necessary. The alignment of the last dimension is always 1 and cannot be set.

set_component_format()

void cgv::data::component_format::set_component_format ( ComponentFormat  _cf )

inherited

set the component names from a standard component format

set the component names from a given component format

set_depth()

void cgv::data::data_format::set_depth ( unsigned int  _depth )

inherited

set the resolution in the third dimension, add dimensions if necessary

set the number of entries in the third dimension

set_height()

void cgv::data::data_format::set_height ( unsigned int  _height )

inherited

set the resolution in the second dimension, add dimensions if necessary

set the number of entries in the second dimension

set_min_filter()

void cgv::render::texture::set_min_filter	(	TextureFilter	_min_filter,
		float	_anisotropy = 2.0f
	)

set the minification filters, if minification is set to TF_ANISOTROP, the second floating point parameter specifies the degree of anisotropy

set_nr_dimensions()

void cgv::data::data_format::set_nr_dimensions ( unsigned int  _d )

inherited

set the number of dimensions of the data set

set the dimension of the data set

set_nr_time_steps()

void cgv::data::data_format::set_nr_time_steps ( unsigned int  _nr_time_steps )

inherited

set the resolution in the last dimension, add dimensions if necessary

set the number of entries in the last dimension

set_resolution()

void cgv::data::data_format::set_resolution ( unsigned int  i, unsigned int  resolution  )

inherited

set the resolution in the i-th dimension, add dimensions if necessary

set the number of data entries in the given dimension

set_width()

void cgv::data::data_format::set_width ( unsigned int  _width )

inherited

set the resolution in the first dimension, add dimensions if necessary

set the number of entries in the first dimension

---

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

• D:/develop/projects/git/cgv/cgv/render/texture.h
• D:/develop/projects/git/cgv/cgv/render/texture.cxx