CGII/framework/include/cgv/render/texture.h

201 lines
11 KiB
C
Raw Normal View History

2018-05-17 13:50:03 +00:00
#pragma once
#include <cgv/data/data_format.h>
#include <cgv/data/data_view.h>
#include <cgv/render/context.h>
#include "lib_begin.h"
namespace cgv {
namespace render {
2018-05-17 14:01:02 +00:00
/** the texture class encapsulates all functionality independent
of the rendering api. */
2018-05-17 13:50:03 +00:00
class CGV_API texture : public texture_base, public cgv::data::data_format
{
2018-05-17 14:01:02 +00:00
protected:
mutable bool state_out_of_date;
int tex_unit;
bool complete_create(context& ctx, bool created);
public:
/**@name methods that can be called without context */
//@{
/** 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 \c cgv::data::component_format::set_component_format()
or a data format as described in \c cgv::data::data_format::set_data_format(). */
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);
/** destruct texture, the destructor can be called without context
if the destruct method has been called or no creation has
taken place */
~texture();
2018-05-17 13:50:03 +00:00
/// change the data format and clear internal format
bool set_data_format(const std::string& description);
/// change component format and clear internal format
2018-05-17 14:01:02 +00:00
void set_component_format(const component_format& cf);
2018-05-17 13:50:03 +00:00
/// change component format and clear internal format
2018-05-17 14:01:02 +00:00
void set_component_format(const std::string& description);
/// set the texture wrap behaviour in s direction
void set_wrap_s(TextureWrap _wrap_s);
/// set the texture wrap behaviour in t direction
void set_wrap_t(TextureWrap _wrap_t);
/// set the texture wrap behaviour in r direction
void set_wrap_r(TextureWrap _wrap_r);
/// return the texture wrap behaviour in s direction
TextureWrap get_wrap_s() const;
/// return the texture wrap behaviour in t direction
TextureWrap get_wrap_t() const;
/// return the texture wrap behaviour in r direction
TextureWrap get_wrap_r() const;
/// set the border color
void set_border_color(const float* rgba) { set_border_color(rgba[0],rgba[1],rgba[2],rgba[3]); }
/// set the border color
void set_border_color(float r, float g, float b, float a = 1.0f);
/** set the minification filters, if minification is set to TF_ANISOTROP,
the second floating point parameter specifies the degree of anisotropy */
void set_min_filter(TextureFilter _min_filter, float _anisotropy = 2.0f);
/// return the minification filter
TextureFilter get_min_filter() const;
/// return the currently set anisotropy
float get_anisotropy() const;
/// set the magnification filter
void set_mag_filter(TextureFilter _mag_filter);
/// return the magnification filter
TextureFilter get_mag_filter() const;
/// set priority with which texture is kept in GPU memory
void set_priority(float _priority);
/// return the priority with which texture is kept in GPU memory
float get_priority() const;
/// set the texture compare mode and function
void set_compare_mode(bool use_compare_function);
/// get the texture compare mode and function
bool get_compare_mode() const;
/// set the texture compare function
void set_compare_function(CompareFunction compare_function);
/// get the texture compare function
CompareFunction get_compare_function() const;
/// check whether mipmaps have been created
bool mipmaps_created() const;
/// ensure the the texture state is synchronized with the GPU settings
void ensure_state(context& ctx) const;
/// check whether textue is enabled
bool is_enabled() const;
/// return the currently used texture unit and -1 for current
int get_tex_unit() const;
//@}
/**@name methods that can be called only with a context */
//@{
/// find the format that matches the one specified in the component format best
void find_best_format(context& ctx, const std::vector<cgv::data::data_view>* palettes = 0);
/** 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. */
bool create(context& ctx, TextureType _tt = TT_UNDEF, unsigned width=-1, unsigned height=-1, unsigned depth=-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. */
bool create_from_image(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);
/** 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. */
bool create_from_image(cgv::data::data_format& df, cgv::data::data_view& dv, context& ctx, const std::string& file_name = "",
unsigned char* clear_color_ptr = 0, int level = -1, int cube_side = -1);
//! 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. */
static bool deduce_file_names(const std::string& file_names, std::vector<std::string>& deduced_names);
//! 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. */
bool create_from_images(context& ctx, const std::string& file_names, int level = -1);
/// write the content of the texture to a file. This method needs support for frame buffer objects.
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;
/** generate mipmaps automatically, only supported if
framebuffer objects are supported by the GPU */
bool generate_mipmaps(context& ctx);
/** 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. */
bool create_from_buffer(context& ctx, int x, int y, int width, int height, int level = -1);
/** 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. */
bool create(context& ctx, const cgv::data::const_data_view& data, int level = -1, int cube_side = -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. */
bool replace(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 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. */
bool replace(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 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. */
bool replace(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 2d texture from the current read buffer.
bool replace_from_buffer(context& ctx, int x, int y, int x_buffer,
int y_buffer, int width, int height, int level = -1);
/// replace a block within a 3d texture or a side from a cube map from the current read buffer.
bool replace_from_buffer(context& ctx, int x, int y, int z_or_cube_side, int x_buffer,
int y_buffer, int width, int height, int level);
/// replace within a slice of a volume or a side of a cube map from the given image
bool replace_from_image(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. */
bool replace_from_image(cgv::data::data_format& df, cgv::data::data_view& dv, context& ctx,
const std::string& file_name, int x, int y, int z_or_cube_side, int level);
/// destruct the texture and free texture memory and handle
bool destruct(context& ctx);
//@}
/**@name methods that change the current gpu context */
//@{
/** enable this texture in the given texture unit, -1 corresponds to
the current unit. */
bool enable(context& ctx, int tex_unit = -1);
/// disable texture and restore state before last enable call
bool disable(context& ctx);
//@}
2018-05-17 13:50:03 +00:00
};
2018-05-17 14:01:02 +00:00
2018-05-17 13:50:03 +00:00
}
}
#include <cgv/config/lib_end.h>