Coin: SoGLBigImage Class Reference

| Coin3D is Free Software, published under the BSD 3-clause license. | https://coin3d.github.io https://www.kongsberg.com/en/kogt/

Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
SoGLBigImage Class Reference

The SoGLBigImage class is used to handle 2D OpenGL textures of any size. More...

`#include <include/Inventor/misc/SoGLBigImage.h>`

Inheritance diagram for SoGLBigImage:

## Public Member Functions
| SoGLBigImage ()
virtual void | unref (SoState *state=NULL)
virtual SoType | getTypeId (void) const
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)
int | initSubImages (const SbVec2s &subimagesize) const
void | handleSubImage (const int idx, SbVec2f &start, SbVec2f &end, SbVec2f &tcmul)
void | applySubImage (SoState *state, const int idx, const float quality, const SbVec2s &projsize)
SbBool | exceededChangeLimit (void)
virtual SoGLDisplayList * | getGLDisplayList (SoState *state)
Public Member Functions inherited from SoGLImage
| SoGLImage ()
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)
void | setFlags (const uint32_t flags)
uint32_t | getFlags (void) const
const SbImage * | getImage (void) const
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 int | setChangeLimit (const int limit)
static void | initClass (void)
Static Public Member Functions inherited from SoGLImage
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
virtual void | unrefOldDL (SoState *state, const uint32_t maxage)
Protected Member Functions inherited from SoGLImage
void | incAge (void) const
void | resetAge (void) const
virtual | ~SoGLImage ()

## Additional Inherited Members
Public Types inherited from SoGLImage
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)

## Detailed Description

The SoGLBigImage class is used to handle 2D OpenGL textures of any size.

This class is internal. To enable/disable big-image texture handling you should use the SoTextureScalePolicy node.

The technique used is the following: split the texture into x*y equal size blocks. All these subtextures are of size 2^n, and are typically quite small (256x256 or smaller). Each triangle is clipped, based on the texture coordinates, into several smaller triangles. The triangles will then be guaranteed to use only one subtexture. Then the triangles are projected onto the screen, and the maximum projected size for each subtexture is calculated. Subtextures outside the viewport will be culled. Each subtexture is then sampled down to a 2^n value close to the projected size, and a GL texture is created with this size. This GL texture is used when rendering triangles that are clipped into that subtexture.

Mipmapping is disabled for SoGLBigImage. Aliasing problems shouldn't occur because the projected size of the texture is calculated on the fly. When mipmapping is enabled, the amount of texture memory used is doubled, and creating the texture object is much slower, so we avoid this for SoGLBigImage.

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

## Constructor & Destructor Documentation

## ◆ SoGLBigImage()

SoGLBigImage::SoGLBigImage | ( | void |  | ) |

Constructor.

## Member Function Documentation

## ◆ unref()

void SoGLBigImage::unref | ( | SoState * | state = NULL | ) |
| virtual

This class has a private destructor 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 from SoGLImage.

## ◆ getClassTypeId()

SoType SoGLBigImage::getClassTypeId | ( | void |  | ) |
| static

This static method returns the SoType object associated with objects of this class.

## ◆ getTypeId()

SoType SoGLBigImage::getTypeId | ( | void |  | ) | const
| virtual

Returns the type identification of an object derived from a class inheriting SoGLImage. This is used for runtime type checking and "downward" casting.

Reimplemented from SoGLImage.

## ◆ setData() [1/2]

void SoGLBigImage::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 from SoGLImage.

## ◆ setData() [2/2]

void SoGLBigImage::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 from SoGLImage.

## ◆ exceededChangeLimit()

SbBool SoGLBigImage::exceededChangeLimit | ( | void |  | ) |

To avoid doing too much work in one frame, there is a limit on the number of subtextures that can be changed each frame. If this limit is exceeded, this function will return TRUE, otherwise FALSE.

See also
  setChangeLimit()

## ◆ setChangeLimit()

int SoGLBigImage::setChangeLimit | ( | const int | limit | ) |
| static

Sets the change limit. Returns the old limit.

See also
  exceededChangeLimit()

Since
  Coin 2.3

## ◆ getGLDisplayList()

SoGLDisplayList * SoGLBigImage::getGLDisplayList | ( | SoState * | state | ) |
| virtual

Returns or creates a SoGLDisplayList to be used for rendering. Returns NULL if no SoGLDisplayList could be created.

Reimplemented from SoGLImage.

## ◆ unrefOldDL()

void SoGLBigImage::unrefOldDL | ( | SoState * | state,
|  | const uint32_t | maxage )
| protectedvirtual

Virtual method that will be called once each frame. The method should unref display lists that have an age bigger or equal to maxage, and increment the age for other display lists.

Reimplemented from SoGLImage.

## ◆ initClass()

void SoGLBigImage::initClass | ( | void |  | ) |
| static

This static method initializes static data for the SoGLBigImage class.

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

- SoGLBigImage.h
- SoGLBigImage.cpp