A data_format describes a multidimensional data block of data entries. More...

#include <data_format.h>

Inheritance diagram for cgv::data::data_format:

Classes
struct	dimension_info

Public Member Functions
	data_format ()
	construct an undefined data format

	data_format (const std::string &description)
	construct from description string, see set_data_format for docu

bool	set_data_format (const std::string &description)
	Set data format from description string, which adds information to the description string of the component format and has the following syntax.

	data_format (size_t _width, cgv::type::info::TypeId _component_type, const std::string &_component_name_list, unsigned align=1, unsigned d0=0, unsigned d1=0, unsigned d2=0, unsigned d3=0)
	construct a 1d data format from width and the information needed to construct a component info

	data_format (size_t _width, cgv::type::info::TypeId _component_type, ComponentFormat _cf, unsigned align=1, unsigned d0=0, unsigned d1=0, unsigned d2=0, unsigned d3=0)
	construct a 1d data format from width and the information needed to construct a component info

	data_format (size_t _width, size_t _height, cgv::type::info::TypeId _component_type, const std::string &_component_name_list, unsigned align=1, unsigned d0=0, unsigned d1=0, unsigned d2=0, unsigned d3=0)
	construct a 2d data format from width and height

	data_format (size_t _width, size_t _height, cgv::type::info::TypeId _component_type, ComponentFormat _cf, unsigned align=1, unsigned d0=0, unsigned d1=0, unsigned d2=0, unsigned d3=0)
	construct a 2d data format from width and height

	data_format (size_t _width, size_t _height, size_t _depth, cgv::type::info::TypeId _component_type, const std::string &_component_name_list, unsigned align=1, unsigned d0=0, unsigned d1=0, unsigned d2=0, unsigned d3=0)
	construct a 3d data format from width, height and depth

	data_format (size_t _width, size_t _height, size_t _depth, cgv::type::info::TypeId _component_type, ComponentFormat _cf, unsigned align=1, unsigned d0=0, unsigned d1=0, unsigned d2=0, unsigned d3=0)
	construct a 3d data format from width, height and depth

	data_format (size_t _width, size_t _height, size_t _depth, size_t _count, cgv::type::info::TypeId _component_type, const std::string &_component_name_list, unsigned align=1, unsigned d0=0, unsigned d1=0, unsigned d2=0, unsigned d3=0)
	construct a 4d data format from width, height, depth and count

	data_format (size_t _width, size_t _height, size_t _depth, size_t _count, cgv::type::info::TypeId _component_type, ComponentFormat _cf, unsigned align=1, unsigned d0=0, unsigned d1=0, unsigned d2=0, unsigned d3=0)
	construct a 4d data format from width, height, depth and count

void	set_dimensions (size_t _d0, size_t _d1=-1, size_t _d2=-1, size_t _d3=-1)
	set the dimensions to the given values

unsigned	get_nr_dimensions () const
	return the number of dimensions of the data set

void	set_nr_dimensions (unsigned _d)
	set the number of dimensions of the data set

size_t	get_resolution (unsigned i) const
	return the resolution in the i-th dimension, or 0 if not defined

size_t	get_width () const
	return the resolution in the first dimension, or 1 if not defined

size_t	get_height () const
	return the resolution in the second dimension, or 1 if not defined

size_t	get_depth () const
	return the resolution in the third dimension, or 1 if not defined

size_t	get_nr_time_steps () const
	return the resolution in the highest dimension, or 1 if not defined

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 i, size_t resolution)
	set the resolution in the i-th dimension, add dimensions if necessary

void	set_width (size_t _width)
	set the resolution in the first dimension, add dimensions if necessary

void	set_height (size_t _height)
	set the resolution in the second dimension, add dimensions if necessary

void	set_depth (size_t _depth)
	set the resolution in the third dimension, add dimensions if necessary

void	set_nr_time_steps (size_t _nr_time_steps)
	set the resolution in the last dimension, add dimensions if necessary

unsigned	get_entry_alignment () const
	return the alignment of entries

unsigned	get_alignment (unsigned i) const
	return the alignment of a given dimension, where the alignment of the last dimension is always 1 and cannot be changed.

void	set_entry_alignment (unsigned _a)
	set the alignment of entries

void	set_alignment (unsigned i, unsigned _a)
	set the alignment of a given dimension, add dimensions if necessary.

unsigned	get_layout_dimension (unsigned dim) const
	return the layout dimension of a given dimension

void	set_layout_dimension (unsigned dim, unsigned layout_dim)
	set the layout dimension of a given dimension, add dimensions if necessary

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

bool	operator== (const data_format &df) const
	comparison between component formats

bool	operator!= (const data_format &df) const
	comparison between component formats

Public Member Functions inherited from cgv::data::component_format
	component_format (const std::string &description)
	construct from description string, see set_component_format for docu

bool	set_component_format (const std::string &description)
	set component format from description string, which has the following syntax.

void	set_components (const std::string &_components)
	comma separated list of component descriptors, for example "R,G,B"

	component_format (cgv::type::info::TypeId _component_type=cgv::type::info::TypeId::TI_UNDEF, const std::string &_component_name_list="", unsigned align=1, unsigned d0=0, unsigned d1=0, unsigned d2=0, unsigned d3=0)
	construct component format from component type, comma or colon separated list of component names, component alignment and bit depths for packed formats

	component_format (cgv::type::info::TypeId _component_type, ComponentFormat cf, unsigned align=1, unsigned d0=0, unsigned d1=0, unsigned d2=0, unsigned d3=0)
	construct component format from component type, standard component format, component alignment and bit depths for packed formats

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

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

void	set_component_format (ComponentFormat _cf)
	set the component names from a standard component format

cgv::type::info::TypeId	get_component_type () const
	return the component type

void	set_component_type (cgv::type::info::TypeId _type_id)
	set the component type

unsigned int	get_entry_size () const
	return the size of one entry of components in bytes

bool	operator== (const component_format &cf) const
	comparison between component formats

bool	operator!= (const component_format &cf) const
	comparison between component formats

Public Member Functions inherited from cgv::data::packing_info
	packing_info (unsigned align=1, unsigned d0=0, unsigned d1=0, unsigned d2=0, unsigned d3=0)
	construct packing information from alignment and bit depths.

void	clear ()
	clear packing info information

unsigned	get_bit_depth (unsigned ci) const
	return the bit depth of the ci-th component

void	set_bit_depth (unsigned ci, unsigned 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 a)
	set the component alignment in bits in the packed case and in bytes in the unpacked case

int	get_signed (unsigned 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 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 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 ci, void *ptr, unsigned v) const
	set the ci-th component of the data entry pointed to by the given pointer of an unsigned packed component

bool	operator== (const packing_info &pi) const
	equal comparison

bool	operator!= (const packing_info &pi) const
	unequal comparison

Protected Attributes
std::vector< dimension_info >	dimensions
	store for each dimension resolution and alignment in a dimension_info struct

Protected Attributes inherited from cgv::data::component_format
cgv::type::info::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

Protected Attributes inherited from cgv::data::packing_info
bool	is_packed: 1

unsigned	bd0: 6

unsigned	bd1: 6

unsigned	bd2: 6

unsigned	bd3: 6

unsigned	ca: 6

Friends
FRIEND_MEMBER_API std::ostream &	operator<< (std::ostream &os, const data_format &df)
	define stream out operator

Additional Inherited Members
Static Public Member Functions inherited from cgv::data::component_format
static const std::string &	get_last_error ()
	returns an error string after parsing of description string has failed

Static Public Member Functions inherited from cgv::data::packing_info
static size_t	align (size_t v, unsigned a)
	return the next integer larger or equal to v which is dividable by a

Protected Member Functions inherited from cgv::data::component_format
void	extract_components ()
	extract components from component string

Protected Member Functions inherited from cgv::data::packing_info
bool	prepare_bit_operation (unsigned ci, void ptr, unsigned &off, unsigned &bd, unsigned &iptr) const

bool	prepare_bit_operation (unsigned ci, const void ptr, unsigned &off, unsigned &bd, const unsigned &iptr) const

unsigned int	get_bit_offset (unsigned ci) const

Static Protected Attributes inherited from cgv::data::component_format
static std::string	last_error
	store the last error that appeared during parsing of a description

Detailed Description

A data_format describes a multidimensional data block of data entries.

It inherits the information stored in component info which describes which components each data entry has. The data_format adds information about the dimensionality and the alignment and resolution in each dimension.

Definition at line 16 of file data_format.h.

Constructor & Destructor Documentation

◆ data_format() [1/10]

cgv::data::data_format::data_format ( )

construct an undefined data format

Definition at line 11 of file data_format.cxx.

Referenced by cgv::render::texture::write_to_file().

◆ data_format() [2/10]

cgv::data::data_format::data_format ( const std::string & description )

explicit

construct from description string, see set_data_format for docu

Definition at line 14 of file data_format.cxx.

References set_data_format().

◆ data_format() [3/10]

cgv::data::data_format::data_format	(	size_t	_width,
		cgv::type::info::TypeId	_component_type,
		const std::string &	_component_name_list,
		unsigned	align = `1`,
		unsigned	d0 = `0`,
		unsigned	d1 = `0`,
		unsigned	d2 = `0`,
		unsigned	d3 = `0`
	)

construct a 1d data format from width and the information needed to construct a component info

Definition at line 101 of file data_format.cxx.

References dimensions.

◆ data_format() [4/10]

cgv::data::data_format::data_format	(	size_t	_width,
		cgv::type::info::TypeId	_component_type,
		ComponentFormat	_cf,
		unsigned	align = `1`,
		unsigned	d0 = `0`,
		unsigned	d1 = `0`,
		unsigned	d2 = `0`,
		unsigned	d3 = `0`
	)

construct a 1d data format from width and the information needed to construct a component info

Definition at line 107 of file data_format.cxx.

References dimensions.

◆ data_format() [5/10]

cgv::data::data_format::data_format	(	size_t	_width,
		size_t	_height,
		cgv::type::info::TypeId	_component_type,
		const std::string &	_component_name_list,
		unsigned	align = `1`,
		unsigned	d0 = `0`,
		unsigned	d1 = `0`,
		unsigned	d2 = `0`,
		unsigned	d3 = `0`
	)

construct a 2d data format from width and height

Definition at line 113 of file data_format.cxx.

References dimensions.

◆ data_format() [6/10]

cgv::data::data_format::data_format	(	size_t	_width,
		size_t	_height,
		cgv::type::info::TypeId	_component_type,
		ComponentFormat	_cf,
		unsigned	align = `1`,
		unsigned	d0 = `0`,
		unsigned	d1 = `0`,
		unsigned	d2 = `0`,
		unsigned	d3 = `0`
	)

construct a 2d data format from width and height

Definition at line 120 of file data_format.cxx.

References dimensions.

◆ data_format() [7/10]

cgv::data::data_format::data_format	(	size_t	_width,
		size_t	_height,
		size_t	_depth,
		cgv::type::info::TypeId	_component_type,
		const std::string &	_component_name_list,
		unsigned	align = `1`,
		unsigned	d0 = `0`,
		unsigned	d1 = `0`,
		unsigned	d2 = `0`,
		unsigned	d3 = `0`
	)

construct a 3d data format from width, height and depth

Definition at line 128 of file data_format.cxx.

References dimensions.

◆ data_format() [8/10]

cgv::data::data_format::data_format	(	size_t	_width,
		size_t	_height,
		size_t	_depth,
		cgv::type::info::TypeId	_component_type,
		ComponentFormat	_cf,
		unsigned	align = `1`,
		unsigned	d0 = `0`,
		unsigned	d1 = `0`,
		unsigned	d2 = `0`,
		unsigned	d3 = `0`
	)

construct a 3d data format from width, height and depth

Definition at line 136 of file data_format.cxx.

References dimensions.

◆ data_format() [9/10]

cgv::data::data_format::data_format	(	size_t	_width,
		size_t	_height,
		size_t	_depth,
		size_t	_count,
		cgv::type::info::TypeId	_component_type,
		const std::string &	_component_name_list,
		unsigned	align = `1`,
		unsigned	d0 = `0`,
		unsigned	d1 = `0`,
		unsigned	d2 = `0`,
		unsigned	d3 = `0`
	)

construct a 4d data format from width, height, depth and count

Definition at line 144 of file data_format.cxx.

References dimensions.

◆ data_format() [10/10]

cgv::data::data_format::data_format	(	size_t	_width,
		size_t	_height,
		size_t	_depth,
		size_t	_count,
		cgv::type::info::TypeId	_component_type,
		ComponentFormat	_cf,
		unsigned	align = `1`,
		unsigned	d0 = `0`,
		unsigned	d1 = `0`,
		unsigned	d2 = `0`,
		unsigned	d3 = `0`
	)

construct a 4d data format from width, height, depth and count

Definition at line 153 of file data_format.cxx.

References dimensions.

Member Function Documentation

◆ get_alignment()

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

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.

Definition at line 239 of file data_format.cxx.

References dimensions, and get_nr_dimensions().

Referenced by cgv::data::data_view_base::data_view_base(), and operator==().

◆ get_component_format()

const component_format & cgv::data::data_format::get_component_format ( ) const

return the component_format info by simple conversion of the this pointer

Definition at line 277 of file data_format.cxx.

Referenced by cgv::media::volume::volume::add_new_component(), cgv::data::data_view::combine_components(), cgv::data::data_view::compose(), cgv::media::volume::volume::get_voxel_size(), operator==(), cgv::render::gl::gl_context::read_frame_buffer(), and cgv::media::volume::volume::replace_component().

◆ get_depth()

size_t cgv::data::data_format::get_depth ( ) const

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

Definition at line 223 of file data_format.cxx.

References get_resolution().

Referenced by cgv::media::volume::volume::add_new_component(), cgv::data::data_view::combine_components(), cgv::media::volume::volume::get_dimensions(), cgv::render::gl::load_texture(), cgv::render::gl::render_to_texture3D(), cgv::media::volume::volume::replace_component(), and cgv::render::gl::replace_texture().

◆ get_entry_alignment()

unsigned cgv::data::data_format::get_entry_alignment ( ) const

return the alignment of entries

Definition at line 233 of file data_format.cxx.

References dimensions, and get_nr_dimensions().

◆ get_height()

size_t cgv::data::data_format::get_height ( ) const

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

Definition at line 219 of file data_format.cxx.

References get_resolution().

◆ get_layout_dimension()

unsigned cgv::data::data_format::get_layout_dimension ( unsigned dim ) const

return the layout dimension of a given dimension

Definition at line 192 of file data_format.cxx.

References dimensions, and get_nr_dimensions().

◆ get_nr_bytes()

size_t cgv::data::data_format::get_nr_bytes ( ) const

return the total number of bytes necessary to store the data

Definition at line 211 of file data_format.cxx.

References cgv::data::component_format::get_entry_size(), and get_nr_entries().

Referenced by cgv::data::data_view::compose(), cgv::data::data_view::data_view(), cgv::data::data_view::data_view(), and cgv::media::volume::volume::volume().

◆ get_nr_dimensions()

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

return the number of dimensions of the data set

Definition at line 172 of file data_format.cxx.

References dimensions.

Referenced by cgv::media::volume::volume::add_new_component(), cgv::render::frame_buffer::attach(), cgv::render::frame_buffer::attach(), cgv::data::data_view::combine_components(), cgv::data::data_view::compose(), cgv::render::texture::create(), cgv::render::gl::create_texture(), cgv::data::data_view_base::data_view_base(), cgv::render::texture::disable(), cgv::render::texture::enable(), cgv::render::texture::generate_mipmaps(), get_alignment(), cgv::media::volume::ooc_sliced_volume::get_dimensions(), cgv::media::volume::volume::get_dimensions(), get_entry_alignment(), get_layout_dimension(), get_nr_entries(), get_nr_time_steps(), get_resolution(), cgv::render::gl::load_texture(), operator==(), cgv::render::texture::replace(), cgv::render::texture::replace(), cgv::media::volume::volume::replace_component(), cgv::render::texture::replace_from_buffer(), cgv::render::gl::replace_texture(), set_alignment(), cgv::render::volume_renderer::set_depth_texture(), set_entry_alignment(), cgv::render::volume_renderer::set_gradient_texture(), set_layout_dimension(), set_nr_time_steps(), set_resolution(), cgv::render::volume_renderer::set_transfer_function_texture(), cgv::render::volume_renderer::set_volume_texture(), and cgv::render::volume_renderer::update_defines().

◆ get_nr_entries()

size_t cgv::data::data_format::get_nr_entries ( ) const

return the total number of data entries

Definition at line 204 of file data_format.cxx.

References get_nr_dimensions(), and get_resolution().

Referenced by get_nr_bytes().

◆ get_nr_time_steps()

size_t cgv::data::data_format::get_nr_time_steps ( ) const

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

Definition at line 227 of file data_format.cxx.

References get_nr_dimensions(), and get_resolution().

Referenced by cgv::media::volume::volume::add_new_component(), cgv::data::data_view::combine_components(), and cgv::media::volume::volume::replace_component().

◆ get_resolution()

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

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

Definition at line 180 of file data_format.cxx.

References dimensions, and get_nr_dimensions().

Referenced by cgv::render::texture::create(), get_depth(), get_height(), get_nr_entries(), get_nr_time_steps(), get_width(), and operator==().

◆ get_width()

size_t cgv::data::data_format::get_width ( ) const

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

Definition at line 215 of file data_format.cxx.

References get_resolution().

◆ operator!=()

bool cgv::data::data_format::operator!= ( const data_format & df ) const

comparison between component formats

Definition at line 297 of file data_format.cxx.

◆ operator==()

bool cgv::data::data_format::operator== ( const data_format & df ) const

comparison between component formats

Definition at line 285 of file data_format.cxx.

References get_alignment(), get_component_format(), get_nr_dimensions(), and get_resolution().

◆ set_alignment()

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

set the alignment of a given dimension, add dimensions if necessary.

The alignment of the last dimension is always 1 and cannot be set.

Definition at line 269 of file data_format.cxx.

References dimensions, and get_nr_dimensions().

◆ set_component_format()

void cgv::data::data_format::set_component_format ( const component_format & cf )

set component_format by simply assigning to a converted this pointer

Definition at line 281 of file data_format.cxx.

Referenced by cgv::media::volume::ooc_sliced_volume::open_read(), cgv::media::volume::volume::set_component_format(), cgv::render::texture::set_component_format(), and cgv::media::volume::volume::set_component_format().

◆ set_data_format()

bool cgv::data::data_format::set_data_format ( const std::string & description )

Set data format from description string, which adds information to the description string of the component format and has the following syntax.

For the definition of the token component_format in the syntax definition refer to the docu of component_format::set_component_format(). If a parse error arises, return false and set the static last_error member, which can be queried with get_last_error().

Syntax definition:

data_format <- component_format['|' alignment_in_bytes] '(' dimension_info (',' dimension_info)* ')'

dimension_info <- resolution [':' layout_dimension]['|' alignment_in_bytes]

- resolution : unsigned int ... number of entries in specified dimension

- layout_dimension : unsigned int ... index of dimension in memory layout, which defaults
                                    to the specified dimension
- alignment_in_bytes : unsigned int ... alignment in the memory layout for entries with index zero
                                        in the specified dimension

In the standard memory layout of for example an image, the entries are arranged line by line, i.e. first the entries of the first line are stored from left to right, followed by the entries of the second line and so on. To change this order of the layout, one can specify for each dimension in the data format a layout dimension which defaults to the dimension index, i.e. if the layout dimensions of all dimensions correspond to the dimension index, the memory layout is starting with the 0-th dimension. To store an image in a columns first memory layout, the layout dimensions would be 1 and 0 for dimensions 0 and 1.

Some examples of valid data format description strings:

"uint8[R,G,B](127|8,256)" ... 127x256 RGB-image, where each line is aligned to multiples of 8
"uint8[R,G,B](127:1,256:0)" ... 127x256 RGB-image stored in column major memory layout
"uint16[L:12,A:12]|4(32,32,32)" ... 32x32x32 12-Bit Luminance Alpha Volume, where each entry is aligned to 4 bytes

Definition at line 18 of file data_format.cxx.

References cgv::data::component_format::clear(), dimensions, cgv::utils::is_integer(), cgv::data::component_format::last_error, cgv::data::component_format::set_component_format(), cgv::utils::tokenizer::set_sep(), and cgv::utils::to_string().

Referenced by data_format(), and cgv::render::texture::set_data_format().