NAME
SoGLImage -
The SoGLImage class is used to handle OpenGL 2D/3D textures.
SYNOPSIS
#include <include/Inventor/misc/SoGLImage.h>
Inherited by SoGLBigImage, and SoGLCubeMapImage.
Public Types
enum Wrap { REPEAT = 0, CLAMP, CLAMP_TO_EDGE, CLAMP_TO_BORDER }
enum ResizeReason { IMAGE = 0, SUBIMAGE, MIPMAP }
enum Flags { SCALE_DOWN = 0x0001, NO_MIPMAP = 0x0002,
LINEAR_MAG_FILTER = 0x0004, LINEAR_MIN_FILTER = 0x0008,
LINEAR_MIPMAP_FILTER = 0x0010, FORCE_TRANSPARENCY_TRUE = 0x0020,
FORCE_TRANSPARENCY_FALSE = 0x0040, FORCE_ALPHA_TEST_TRUE =
0x0080, FORCE_ALPHA_TEST_FALSE = 0x0100, INVINCIBLE = 0x0200,
RECTANGLE = 0x0400, COMPRESSED = 0x0800, USE_QUALITY_VALUE =
0X8000 }
typedef SbBool SoGLImageResizeCB (SoState *state, const SbVec3s
&newsize, unsigned char *destbuffer, ResizeReason reason, void
*closure, class SoGLImage *image)
Public Member Functions
SoGLImage ()
virtual void unref (SoState *state=NULL)
virtual SoType getTypeId (void) const
virtual SbBool isOfType (SoType type) const
void setGLDisplayList (SoGLDisplayList *dl, SoState *state, const Wrap
wraps=REPEAT, const Wrap wrapt=REPEAT, const float quality=0.5f)
void setPBuffer (SoState *state, void *context, const Wrap
wraps=REPEAT, const Wrap wrapt=REPEAT, const float quality=0.5f)
void setData (const unsigned char *bytes, const SbVec2s &size, const
int numcomponents, const Wrap wraps=REPEAT, const Wrap
wrapt=REPEAT, const float quality=0.5f, const int border=0, SoState
*createinstate=NULL)
void setData (const unsigned char *bytes, const SbVec3s &size, const
int numcomponents, const Wrap wraps=REPEAT, const Wrap
wrapt=REPEAT, const Wrap wrapr=REPEAT, const float quality=0.5f,
const int border=0, SoState *createinstate=NULL)
virtual void setData (const SbImage *image, const Wrap wraps=REPEAT,
const Wrap wrapt=REPEAT, const float quality=0.5f, const int
border=0, SoState *createinstate=NULL)
virtual void setData (const SbImage *image, const Wrap wraps, const
Wrap wrapt, const Wrap wrapr, const float quality=0.5f, const int
border=0, SoState *createinstate=NULL)
void setFlags (const uint32_t flags)
uint32_t getFlags (void) const
const SbImage * getImage (void) const
virtual SoGLDisplayList * getGLDisplayList (SoState *state)
SbBool hasTransparency (void) const
SbBool useAlphaTest (void) const
Wrap getWrapS (void) const
Wrap getWrapT (void) const
Wrap getWrapR (void) const
float getQuality (void) const
uint32_t getGLImageId (void) const
void setEndFrameCallback (void(*cb)(void *), void *closure)
int getNumFramesSinceUsed (void) const
Static Public Member Functions
static SoType getClassTypeId (void)
static void beginFrame (SoState *state)
static void tagImage (SoState *state, SoGLImage *image)
static void endFrame (SoState *state)
static void setDisplayListMaxAge (const uint32_t maxage)
static void freeAllImages (SoState *state=NULL)
static void initClass (void)
static void setResizeCallback (SoGLImageResizeCB *f, void *closure)
Protected Member Functions
void incAge (void) const
void resetAge (void) const
virtual void unrefOldDL (SoState *state, const uint32_t maxage)
virtual ~SoGLImage ()
Detailed Description
The SoGLImage class is used to handle OpenGL 2D/3D textures.
A number of environment variables can be set to control how textures
are created. This is useful to tune Coin to fit your system. E.g. if
you are running on a laptop, it might be a good idea to disable linear
filtering and mipmaps.
· COIN_TEX2_LINEAR_LIMIT: Linear filtering is enabled if
Complexity::textureQuality is greater or equal to this value. Default
value is 0.2.
· COIN_TEX2_MIPMAP_LIMIT: Mipmaps are created if textureQuality is
greater or equal to this value. Default value is 0.5.
· COIN_TEX2_LINEAR_MIPMAP_LIMIT: Linear filtering between mipmap levels
is enabled if textureQuality is greater or equal to this value.
Default value is 0.8.
· COIN_TEX2_SCALEUP_LIMIT: Textures with width or height not equal to a
power of two will always be scaled up if textureQuality is greater or
equal to this value. Default value is 0.7. If textureQuality is lower
than this value, and the width or height is larger than 256 pixels,
the texture is only scaled up if it’s relatively close to the next
power of two size. This could save a lot of texture memory.
· COIN_TEX2_USE_GLTEXSUBIMAGE: When set, and when the new texture data
has the same attributes as the old data, glTexSubImage() will be used
to copy new data into the texture instead of recreating the texture.
This is not enabled by default, since it seems to trigger a bug in
the Linux nVidia drivers. It just happens in some unreproducable
cases. It could be a bug in our glTexSubImage() code, of course. :)
· COIN_TEX2_USE_SGIS_GENERATE_MIPMAP: When set, use the
GL_SGIS_generate_mip extension (if available) to generate mipmaps,
otherwise use a fast internal routine to generate them. Use of
SGIS_generate_mipmap is not enabled by default since we suspect some
ATi drivers have problems with this extensions.
· COIN_ENABLE_CONFORMANT_GL_CLAMP: When set, GL_CLAMP will be used when
SoGLImage::CLAMP is specified as the texture wrap mode. By default
GL_CLAMP_TO_EDGE is used, since this is usually what people want. See
http://www.opengl.org/discussion_boards/ubb/Forum3/HTML/0073.html
for a discussion regarding GL_CLAMP and GL_CLAMP_TO_EDGE.
· COIN_TEX2_ANISOTROPIC_LIMIT: Anisotropic filtering is enabled for
textures when the texture quality is higher than this value. Default
value is 0.85
Be aware that this class is an extension for Coin, and it is not
available in the original SGI Open Inventor v2.1 API.
Since:
Coin 2.0
Member Typedef Documentation
bool SoGLImage::SoGLImageResizeCB Image resize callback type. If registered
using setResizeCallback(), this function will be called whenever Coin
needs to resize an image. The function will be called both for 2D and
3D images.
state is the current state at the time of resizing. newsize is the
requested new image size. Note that the z size of a 2D image is 0.
destbuffer is a pre-allocated buffer big enough to hold the pixels for
the resized image. The # of bytes per pixel is the same as for the
original image. reason is a hint about why the image is resized. At the
moment, only IMAGE is supported. image is the original image.
Return value: TRUE if the resize ahs been resized, FALSE if not. If
FALSE is returned, Coin will resize the image instead.
Member Enumeration Documentation
enum SoGLImage::Wrap Used to specify how texture coordinates < 0.0 and >
1.0 should be handled. It can either be repeated (REPEAT), clamped
(CLAMP) or clamped to edge (CLAMP_TO_EDGE), which is useful when tiling
textures. Since 2002-11-18, CLAMP will be treated as CLAMP_TO_EDGE. The
environment variable COIN_ENABLE_CONFORMANT_GL_CLAMP can be used to
override this behaviour.
enum SoGLImage::ResizeReason Sent as a parameter to SoGLImageResizeCB as a
hint to why an image is being resized. IMAGE means that a whole image
is being initially resized (e.g. a texture image). SUBIMAGE and MIPMAP
are not in use and reserved for future use.
enum SoGLImage::Flags Can be used to tune/optimize the GL texture handling.
Normally the texture quality will be used to decide scaling and
filtering, and the image data will be scanned to decide if the image is
(partly) transparent, and if the texture can be rendered using the
cheaper alpha test instead of blending if it does contain transparency.
If you know the contents of your texture image, or if you have special
requirements on how the texture should be rendered, you can set the
flags using the SoGLImage::setFlags() method.
Constructor & Destructor Documentation
SoGLImage::SoGLImage (void) Constructor.
SoGLImage::~SoGLImage () [protected, virtual] Destructor.
Member Function Documentation
void SoGLImage::unref (SoState * state = NULL) [virtual] This class has a
private destuctor since we want users to supply the current GL state
when deleting the image. This is to make sure gl texture objects are
freed as soon as possible. If you supply NULL to this method, the gl
texture objects won’t be deleted until the next time an GLRenderAction
is applied in the image’s cache context(s).
Reimplemented in SoGLBigImage, and SoGLCubeMapImage.
SoType SoGLImage::getClassTypeId (void) [static] Returns the type id for
this class.
Reimplemented in SoGLBigImage, and SoGLCubeMapImage.
SoType SoGLImage::getTypeId (void) const [virtual] Returns the type id for
an SoGLImage instance.
Reimplemented in SoGLBigImage, and SoGLCubeMapImage.
SbBool SoGLImage::isOfType (SoType type) const [virtual] Returns whether an
SoGLImage instance inherits (or is of) type type.
void SoGLImage::setGLDisplayList (SoGLDisplayList * dl, SoState * state,
const Wrap wraps = REPEAT, const Wrap wrapt = REPEAT, const float
quality = 0.5f) Can be used for creating a custom OpenGL texture inside
an SoGLImage instance.
Example use (creates a depth texture):
SoGLDisplayList * depthmap = new SoGLDisplayList(state,
SoGLDisplayList::TEXTURE_OBJECT); depthmap->ref();
depthmap->open(state);
glTexImage2D(GL_TEXTURE_2D, 0, GL_DEPTH_COMPONENT, //
GL_DEPTH_COMPONENT24 size[0], size[1], 0, GL_DEPTH_COMPONENT,
GL_UNSIGNED_BYTE, NULL);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
depthmap->close(state);
SoGLImage * image = new SoGLImage; image->setGLDisplayList(depthmap,
state);
Since:
Coin 2.5
void SoGLImage::setPBuffer (SoState * state, void * pbuffer, const Wrap
wraps = REPEAT, const Wrap wrapt = REPEAT, const float quality = 0.5f)
Sets the pbuffer for this texture. Experimental code, use with care.
void SoGLImage::setData (const unsigned char * bytes, const SbVec2s & size,
const int numcomponents, const Wrap wraps = REPEAT, const Wrap wrapt =
REPEAT, const float quality = 0.5f, const int border = 0, SoState *
createinstate = NULL) 2D setData() wrapper. Supplies raw data, size and
numcomponents instead of an SbImage. Creates a temporary image, then
calls the read setData().
This is an overloaded member function, provided for convenience. It
differs from the above function only in what argument(s) it accepts.
void SoGLImage::setData (const unsigned char * bytes, const SbVec3s & size,
const int numcomponents, const Wrap wraps = REPEAT, const Wrap wrapt =
REPEAT, const Wrap wrapr = REPEAT, const float quality = 0.5f, const
int border = 0, SoState * createinstate = NULL) 3D setData() wrapper.
Supplies raw data, size and numcomponents instead of an SbImage.
Creates a temporary image, then calls the read setData().
This is an overloaded member function, provided for convenience. It
differs from the above function only in what argument(s) it accepts.
void SoGLImage::setData (const SbImage * image, const Wrap wraps = REPEAT,
const Wrap wrapt = REPEAT, const float quality = 0.5f, const int border
= 0, SoState * createinstate = NULL) [virtual] Convenience 2D wrapper
function around the 3D setData().
Reimplemented in SoGLBigImage, and SoGLCubeMapImage.
void SoGLImage::setData (const SbImage * image, const Wrap wraps, const
Wrap wrapt, const Wrap wrapr, const float quality = 0.5f, const int
border = 0, SoState * createinstate = NULL) [virtual] Sets the data for
this GL image. Should only be called when one of the parameters have
changed, since this will cause the GL texture object to be recreated.
Caller is responsible for sending legal Wrap values. CLAMP_TO_EDGE is
only supported on OpenGL v1.2 implementations, and as an extension on
some earlier SGI implementations (GL_SGIS_texture_edge_clamp).
For now, if quality > 0.5 when created, we create mipmaps, otherwise a
regular texture is created. Be aware, if you for instance create a
texture with texture quality 0.4, and then later try to apply the
texture with a texture quality greater than 0.5, the texture object
will be recreated as a mipmap texture object. This will happen only
once though, of course.
If border != 0, the OpenGL texture will be created with this border
size. Be aware that this might be extremely slow on most PC hardware.
Normally, the OpenGL texture object isn’t created until the first time
it is needed, but if createinstate is != NULL, the texture object is
created immediately. This is useful if you use a temporary buffer to
hold the texture data. Be careful when using this feature, since the
texture data might be needed at a later stage (for instance to create a
texture object for another context). It will not be possible to create
texture objects for other cache contexts when createinstate is != NULL.
Also if createinstate is supplied, and all the attributes are the same
as the current data in the image, glTexSubImage() will be used to
insert the image data instead of creating a new texture object. This is
much faster on most OpenGL drivers, and is very useful, for instance
when doing animated textures.
If you supply NULL for image, the instance will be reset, causing all
display lists and memory to be freed.
Reimplemented in SoGLBigImage, and SoGLCubeMapImage.
void SoGLImage::setFlags (const uint32_t flags) Sets flags to control how
the texture is handled/initialized.
uint32_t SoGLImage::getFlags (void) const Returns the flags.
See also:
setFlags()
const SbImage * SoGLImage::getImage (void) const Returns a pointer to the
image data.
SoGLDisplayList * SoGLImage::getGLDisplayList (SoState * state) [virtual]
Returns or creates a SoGLDisplayList to be used for rendering. Returns
NULL if no SoDLDisplayList could be created.
Reimplemented in SoGLBigImage, and SoGLCubeMapImage.
SbBool SoGLImage::hasTransparency (void) const Returns TRUE if this texture
has some pixels with alpha != 255
SbBool SoGLImage::useAlphaTest (void) const Returns TRUE if this image has
some alpha value != 255, and all these values are 0. If this is the
case, alpha test can be used to render this texture instead of for
instance blending, which is usually slower and might yield z-buffer
artifacts.
SoGLImage::Wrap SoGLImage::getWrapS (void) const Returns the wrap strategy
for the S (horizontal) direction.
SoGLImage::Wrap SoGLImage::getWrapT (void) const Returns the wrap strategy
for the T (vertical) direction.
SoGLImage::Wrap SoGLImage::getWrapR (void) const Returns the wrap strategy
for the R (depth) direction.
float SoGLImage::getQuality (void) const Returns the texture quality for
this texture image.
Since:
Coin 2.5
uint32_t SoGLImage::getGLImageId (void) const Returns an unique if for this
GL image. This id can be used to test for changes in an SoGLImage’s
internal data.
void SoGLImage::unrefOldDL (SoState * state, const uint32_t maxage)
[protected, virtual] Virtual method that will be called once each
frame. The method should unref display lists that has an age bigger or
equal to maxage, and increment the age for other display lists.
Reimplemented in SoGLBigImage.
void SoGLImage::beginFrame (SoState * state) [static] When doing texture
resource control, call this method before rendering the scene,
typically in the viewer’s actualRedraw(). state should be your
SoGLRenderAction state.
See also:
endFrame(), tagImage(), setDisplayListMaxAge()
void SoGLImage::tagImage (SoState * state, SoGLImage * image) [static]
Should be called when a texture image is used. In Coin this is handled
by SoGLTextureImageElement, but if you use an SoGLImage on your own,
you should call this method to avoid that the display list is deleted
too soon. state should be your SoGLRenderAction state, image the image
you are about to use/have used.
void SoGLImage::endFrame (SoState * state) [static] Should be called after
your scene is rendered. Old display lists will be deleted when you call
this method. state should be your SoGLRenderAction state.
See also:
beginFrame(), tagImage(), setDisplayListMaxAge()
void SoGLImage::setDisplayListMaxAge (const uint32_t maxage) [static] Set
the maximum age for a texture object/display list. The age of an image
is the number of frames since it has been used. Default maximum age is
60.
void SoGLImage::freeAllImages (SoState * state = NULL) [static] Free all GL
images currently used. This can be used to help the operating system
and/or OpenGL driver’s resource handling. If you know you’re not going
to render for a while, maybe you’re switching to a different
application or something, calling this method could be a good idea
since it will release all the texture memory used by your application.
void SoGLImage::initClass (void) [static] This API member is considered
internal to the library, as it is not likely to be of interest to the
application programmer.
Reimplemented in SoGLBigImage, and SoGLCubeMapImage.
void SoGLImage::setResizeCallback (SoGLImageResizeCB * f, void * closure)
[static] Sets a custom image resize function.
Since:
Coin 2.5
Author
Generated automatically by Doxygen for Coin from the source code.