Coin: SoVRMLImageTexture Class Reference

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

SoVRMLImageTexture Class Reference
VRML97 Classes

The SoVRMLImageTexture class is used for mapping a texture file onto geometry. More...

`#include <Inventor/VRMLnodes/SoVRMLImageTexture.h>`

Inheritance diagram for SoVRMLImageTexture:

## Public Member Functions
virtual SoType | getTypeId (void) const
| SoVRMLImageTexture (void)
void | allowPrequalifyFile (SbBool enable)
virtual void | doAction (SoAction *action)
virtual void | GLRender (SoGLRenderAction *action)
virtual void | callback (SoCallbackAction *action)
virtual void | rayPick (SoRayPickAction *action)
void | setImage (const SbImage &image)
const SbImage * | getImage (void) const
Public Member Functions inherited from SoNode
void | setOverride (const SbBool state)
SbBool | isOverride (void) const
void | setNodeType (const NodeType type)
NodeType | getNodeType (void) const
virtual SoNode * | copy (SbBool copyconnections=FALSE) const
virtual SbBool | affectsState (void) const
virtual void | GLRenderBelowPath (SoGLRenderAction *action)
virtual void | GLRenderInPath (SoGLRenderAction *action)
virtual void | GLRenderOffPath (SoGLRenderAction *action)
virtual void | getBoundingBox (SoGetBoundingBoxAction *action)
virtual void | getMatrix (SoGetMatrixAction *action)
virtual void | handleEvent (SoHandleEventAction *action)
virtual void | pick (SoPickAction *action)
virtual void | search (SoSearchAction *action)
virtual void | write (SoWriteAction *action)
virtual void | audioRender (SoAudioRenderAction *action)
virtual void | getPrimitiveCount (SoGetPrimitiveCountAction *action)
virtual void | grabEventsSetup (void)
virtual void | grabEventsCleanup (void)
virtual void | startNotify (void)
virtual void | notify (SoNotList *l)
SbUniqueId | getNodeId (void) const
virtual SoChildList * | getChildren (void) const
virtual void | writeInstance (SoOutput *out)
virtual SoNode * | addToCopyDict (void) const
virtual void | copyContents (const SoFieldContainer *from, SbBool copyconnections)
virtual SoFieldContainer * | copyThroughConnection (void) const
Public Member Functions inherited from SoFieldContainer
void | setToDefaults (void)
SbBool | hasDefaultValues (void) const
SbBool | fieldsAreEqual (const SoFieldContainer *container) const
void | copyFieldValues (const SoFieldContainer *container, SbBool copyconnections=FALSE)
SbBool | set (const char *const fielddata)
void | get (SbString &fielddata)
virtual int | getFields (SoFieldList &l) const
virtual int | getAllFields (SoFieldList &l) const
virtual SoField * | getField (const SbName &name) const
virtual SoField * | getEventIn (const SbName &name) const
virtual SoField * | getEventOut (const SbName &name) const
SbBool | getFieldName (const SoField *const field, SbName &name) const
SbBool | enableNotify (const SbBool flag)
SbBool | isNotifyEnabled (void) const
SbBool | set (const char *fielddata, SoInput *input)
void | get (SbString &fielddata, SoOutput *out)
virtual SbBool | validateNewFieldValue (SoField *field, void *newval)
virtual void | addWriteReference (SoOutput *out, SbBool isfromfield=FALSE)
SbBool | getIsBuiltIn (void) const
virtual void | getFieldsMemorySize (size_t &managed, size_t &unmanaged) const
void | setUserData (void *userdata) const
void * | getUserData (void) const
Public Member Functions inherited from SoBase
void | ref (void) const
void | unref (void) const
void | unrefNoDelete (void) const
int32_t | getRefCount (void) const
void | touch (void)
SbBool | isOfType (SoType type) const
| Returns `TRUE` if the type of this object is either of the same type or inherited from type.
virtual SbName | getName (void) const
virtual void | setName (const SbName &newname)
void | addAuditor (void *const auditor, const SoNotRec::Type type)
void | removeAuditor (void *const auditor, const SoNotRec::Type type)
const SoAuditorList & | getAuditors (void) const
SbBool | shouldWrite (void)
void | assertAlive (void) const

## Static Public Member Functions
static SoType | getClassTypeId (void)
static void | initClass (void)
static void | setDelayFetchURL (const SbBool onoff)
static void | setPrequalifyFileCallBack (VRMLPrequalifyFileCallback *cb, void *closure)
static void | setImageDataMaxAge (const uint32_t maxage)
Static Public Member Functions inherited from SoVRMLTexture
static SoType | getClassTypeId (void)
static void | initClass (void)
Static Public Member Functions inherited from SoNode
static uint32_t | getCompatibilityTypes (const SoType &nodetype)
static SoType | getClassTypeId (void)
static SoNode * | getByName (const SbName &name)
static int | getByName (const SbName &name, SoNodeList &l)
static void | initClass (void)
| Sets up initialization for data common to all instances of this class, like submitting necessary information to the Coin type system.
static void | initClasses (void)
static SbUniqueId | getNextNodeId (void)
static int | getActionMethodIndex (const SoType type)
static void | getBoundingBoxS (SoAction *action, SoNode *node)
static void | GLRenderS (SoAction *action, SoNode *node)
static void | callbackS (SoAction *action, SoNode *node)
static void | getMatrixS (SoAction *action, SoNode *node)
static void | handleEventS (SoAction *action, SoNode *node)
static void | pickS (SoAction *action, SoNode *node)
static void | rayPickS (SoAction *action, SoNode *node)
static void | searchS (SoAction *action, SoNode *node)
static void | writeS (SoAction *action, SoNode *node)
static void | audioRenderS (SoAction *action, SoNode *node)
static void | getPrimitiveCountS (SoAction *action, SoNode *node)
Static Public Member Functions inherited from SoFieldContainer
static void | initClass (void)
| Sets up initialization for data common to all instances of this class, like submitting necessary information to the Coin type system.
static SoType | getClassTypeId (void)
| This static method returns the SoType object associated with objects of this class.
static void | cleanupClass (void)
static void | initCopyDict (void)
static void | addCopy (const SoFieldContainer *orig, const SoFieldContainer *copy)
static SoFieldContainer * | checkCopy (const SoFieldContainer *orig)
static SoFieldContainer * | findCopy (const SoFieldContainer *orig, const SbBool copyconnections)
static void | copyDone (void)
Static Public Member Functions inherited from SoBase
static void | initClass (void)
| Sets up initialization for data common to all instances of this class, like submitting necessary information to the Coin type system.
static SoType | getClassTypeId (void)
| This static method returns the SoType object associated with objects of this class.
static void | addName (SoBase *const base, const char *const name)
static void | removeName (SoBase *const base, const char *const name)
static void | incrementCurrentWriteCounter (void)
static void | decrementCurrentWriteCounter (void)
static SoBase * | getNamedBase (const SbName &name, SoType type)
static int | getNamedBases (const SbName &name, SoBaseList &baselist, SoType type)
static SbBool | read (SoInput *input, SoBase *&base, SoType expectedtype)
static void | setInstancePrefix (const SbString &c)
static void | setTraceRefs (SbBool trace)
static SbBool | getTraceRefs (void)
static SbBool | connectRoute (SoInput *input, const SbName &fromnodename, const SbName &fromfieldname, const SbName &tonodename, const SbName &tofieldname)
static SbBool | readRoute (SoInput *input)

## Public Attributes
SoMFString | url
Public Attributes inherited from SoVRMLTexture
SoSFBool | repeatS
SoSFBool | repeatT

## Protected Member Functions
virtual const SoFieldData * | getFieldData (void) const
virtual | ~SoVRMLImageTexture ()
virtual SbBool | readInstance (SoInput *in, unsigned short flags)
int | getReadStatus (void) const
void | setReadStatus (int status)
Protected Member Functions inherited from SoVRMLTexture
| SoVRMLTexture (void)
virtual | ~SoVRMLTexture ()
Protected Member Functions inherited from SoNode
| SoNode (void)
virtual | ~SoNode ()
Protected Member Functions inherited from SoFieldContainer
| SoFieldContainer (void)
virtual | ~SoFieldContainer ()
Protected Member Functions inherited from SoBase
| SoBase (void)
virtual | ~SoBase ()
virtual void | destroy (void)
SbBool | hasMultipleWriteRefs (void) const
SbBool | writeHeader (SoOutput *out, SbBool isgroup, SbBool isengine) const
void | writeFooter (SoOutput *out) const
virtual const char * | getFileFormatName (void) const
virtual SoNotRec | createNotRec (void)

## Static Protected Member Functions
static const SoFieldData ** | getFieldDataPtr (void)
Static Protected Member Functions inherited from SoVRMLTexture
static const SoFieldData ** | getFieldDataPtr (void)
Static Protected Member Functions inherited from SoNode
static const SoFieldData ** | getFieldDataPtr (void)
static void | setNextActionMethodIndex (int index)
static int | getNextActionMethodIndex (void)
static void | incNextActionMethodIndex (void)
static void | setCompatibilityTypes (const SoType &nodetype, const uint32_t bitmask)
Static Protected Member Functions inherited from SoBase
static uint32_t | getCurrentWriteCounter (void)
static void | staticDataLock (void)
static void | staticDataUnlock (void)

## Additional Inherited Members
Public Types inherited from SoNode
enum | NodeType { INVENTOR = 0x0000 , VRML1 = 0x0001 , VRML2 = 0x0002 , INVENTOR_1 = 0x0004 , INVENTOR_2_0 = 0x0008 , INVENTOR_2_1 = 0x0010 , INVENTOR_2_5 = 0x0020 , INVENTOR_2_6 = 0x0040 , COIN_1_0 = 0x0080 , COIN_2_0 = 0x0100 , EXTENSION = 0x0200 , COIN_2_2 = 0x0400 , COIN_2_3 = 0x0800 , COIN_2_4 = 0x1000 , INVENTOR_5_0 = 0x2000 , COIN_2_5 = 0x4000 , COIN_3_0 = 0x8000 , INVENTOR_6_0 = 0x10000 , COIN_4_0 = 0x20000 }
Protected Types inherited from SoBase
enum | BaseFlags { IS_ENGINE = 0x01 , IS_GROUP = 0x02 }
Protected Attributes inherited from SoNode
SbUniqueId | uniqueId
Protected Attributes inherited from SoFieldContainer
SbBool | isBuiltIn
Static Protected Attributes inherited from SoNode
static SbUniqueId | nextUniqueId = 1
static int | nextActionMethodIndex = 0

## Detailed Description

The SoVRMLImageTexture class is used for mapping a texture file onto geometry.

The detailed class documentation is taken verbatim from the VRML97 standard (ISO/IEC 14772-1:1997). It is copyright The Web3D Consortium, and is used by permission of the Consortium:

    ImageTexture {
      exposedField MFString url     []
      field        SFBool   repeatS TRUE
      field        SFBool   repeatT TRUE
    }

The ImageTexture node defines a texture map by specifying an image file and general parameters for mapping to geometry. Texture maps are defined in a 2D coordinate system (s, t) that ranges from [0.0, 1.0] in both directions. The bottom edge of the image corresponds to the S-axis of the texture map, and left edge of the image corresponds to the T-axis of the texture map. The lower-left pixel of the image corresponds to s=0, t=0, and the top-right pixel of the image corresponds to s=1, t=1. These relationships are depicted in Figure 6.9.

Figure 6.9

The texture is read from the URL specified by the url field. When the url field contains no values ([]), texturing is disabled. Browsers shall support the JPEG and PNG image file formats. In addition, browsers may support other image formats (e.g. CGM) which can be rendered into a 2D image. Support for the GIF format is also recommended (including transparency).

Details on the url field can be found in 4.5, VRML and the World Wide Web.

See 4.6.11, Texture maps (http://www.web3d.org/documents/specifications/14772/V2.0/part1/concepts.html#4.6.11), for a general description of texture maps.

See 4.14, Lighting model (http://www.web3d.org/documents/specifications/14772/V2.0/part1/concepts.html#4.14), for a description of lighting equations and the interaction between textures, materials, and geometry appearance.

The repeatS and repeatT fields specify how the texture wraps in the S and T directions. If repeatS is TRUE (the default), the texture map is repeated outside the [0.0, 1.0] texture coordinate range in the S direction so that it fills the shape. If repeatS is FALSE, the texture coordinates are clamped in the S direction to lie within the [0.0, 1.0] range. The repeatT field is analogous to the repeatS field.

The rest of this class documentation is not from the VRML97 standards documentation, but was written specifically for the Coin3D API documentation.
One common flaw with many programs that have support for exporting VRML or Inventor files, is that the same texture file is exported several times, but as different nodes. This can cause excessive texture memory usage and slow rendering. Below is an example program that fixes this by replacing all instances of the same texture with a pointer to the first node:

#include <Inventor/actions/SoSearchAction.h>
#include <Inventor/actions/SoWriteAction.h>
#include <Inventor/VRMLnodes/SoVRMLGroup.h>
#include <Inventor/VRMLnodes/SoVRMLImageTexture.h>
#include <Inventor/VRMLnodes/SoVRMLAppearance.h>
#include <Inventor/SoDB.h>
#include <Inventor/SoInput.h>
#include <Inventor/SoOutput.h>
#include <cassert>
int main(int argc, char ** argv)
{
if (argc < 2) return -1;
SoDB::init();
SoInput in;
if (!in.openFile(argv[1])) return -1;
if (!in.isFileVRML2()) return -1; // file is not a vrml2 file
SoVRMLGroup * root = SoDB::readAllVRML(&in);
if (!root) return -1;
root->ref();
SoSearchAction sa;
sa.setType(SoVRMLImageTexture::getClassTypeId());
sa.setInterest(SoSearchAction::ALL);
sa.setSearchingAll(TRUE);
sa.apply(root);
SoPathList & pl = sa.getPaths();
SbDict namedict;
for (int i = 0; i < pl.getLength(); i++) {
SoFullPath * p = (SoFullPath*) pl[i];
if (p->getTail()->isOfType(SoVRMLImageTexture::getClassTypeId())) {
SoVRMLImageTexture * tex = (SoVRMLImageTexture*) p->getTail();
if (tex->url.getNum()) {
// FIXME: we only check the first name here. Should really check all of them
SbName name = tex->url[0].getString();
unsigned long key = (unsigned long) ((void*) name.getString());
void * tmp;
if (!namedict.find(key, tmp)) {
(void) namedict.enter(key, tex);
}
else if (tmp != (void*) tex) {
SoNode * parent = p->getNodeFromTail(1);
if (parent->isOfType(SoVRMLAppearance::getClassTypeId())) {
((SoVRMLAppearance*)parent)->texture = (SoNode*) tmp;
}
else {
// not a valid VRML2 file. Print a warning or something.
}
}
}
}
}
sa.reset();
SoOutput out;
out.setHeaderString("#VRML V2.0 utf8");
SoWriteAction wa(&out);
wa.apply(root);
root->unref();
}
SbDict
The SbDict class organizes a dictionary of keys and values.
Definition SbDict.h:63
SbDict::enter
SbBool enter(const Key key, void *const value)
Definition SbDict.cpp:165
SbDict::find
SbBool find(const Key key, void *&value) const
Definition SbDict.cpp:176
SbName
The SbName class stores strings by reference.
Definition SbName.h:40
SbName::getString
const char * getString(void) const
Definition SbName.cpp:144
SbPList::getLength
int getLength(void) const
Definition lists/SbPList.h:103
SoAction::apply
virtual void apply(SoNode *root)
Definition SoAction.cpp:463
SoBase::unref
void unref(void) const
Definition SoBase.cpp:530
SoBase::isOfType
SbBool isOfType(SoType type) const
Returns TRUE if the type of this object is either of the same type or inherited from type.
Definition SoBase.cpp:631
SoBase::ref
void ref(void) const
Definition SoBase.cpp:478
SoDB::readAllVRML
static SoVRMLGroup * readAllVRML(SoInput *input)
Definition SoDB.cpp:696
SoDB::init
static void init(void)
Definition SoDB.cpp:200
SoFullPath
The SoFullPath class allows examination of hidden children in paths.
Definition SoFullPath.h:38
SoFullPath::getTail
SoNode * getTail(void) const
Definition SoFullPath.cpp:84
SoFullPath::getNodeFromTail
SoNode * getNodeFromTail(const int index) const
Definition SoFullPath.cpp:95
SoInput
The SoInput class is an abstraction of file import functionality.
Definition SoInput.h:61
SoInput::openFile
virtual SbBool openFile(const char *fileName, SbBool okIfNotFound=FALSE)
Definition SoInput.cpp:507
SoInput::isFileVRML2
SbBool isFileVRML2(void)
Definition SoInput.cpp:2441
SoMField::getNum
int getNum(void) const
Definition SoMField.h:102
SoNode
The SoNode class is the base class for nodes used in scene graphs.
Definition SoNode.h:56
SoOutput::setHeaderString
virtual void setHeaderString(const SbString &str)
Definition SoOutput.cpp:674
SoPathList
The SoPathList class is a container for pointers to SoPath objects.
Definition SoPathList.h:40
SoSearchAction
The SoSearchAction class provides methods for searching through scene graphs.
Definition SoSearchAction.h:44
SoSearchAction::setType
void setType(const SoType type, const SbBool chkderived=TRUE)
Definition SoSearchAction.cpp:216
SoSearchAction::ALL
@ ALL
Definition SoSearchAction.h:56
SoSearchAction::reset
void reset(void)
Definition SoSearchAction.cpp:382
SoSearchAction::setSearchingAll
void setSearchingAll(const SbBool searchall)
Definition SoSearchAction.cpp:319
SoSearchAction::getPaths
SoPathList & getPaths(void)
Definition SoSearchAction.cpp:372
SoSearchAction::setInterest
void setInterest(const Interest interest)
Definition SoSearchAction.cpp:290
SoVRMLAppearance
The SoVRMLAppearance class specifies visual properties for shapes.
Definition SoVRMLAppearance.h:43
SoVRMLAppearance::getClassTypeId
static SoType getClassTypeId(void)
Definition Appearance.cpp:135
SoVRMLGroup
The SoVRMLGroup class is used for grouping VRML nodes.
Definition SoVRMLGroup.h:45
SoVRMLImageTexture::SoVRMLImageTexture
SoVRMLImageTexture(void)
Definition ImageTexture.cpp:350
SoVRMLImageTexture::getClassTypeId
static SoType getClassTypeId(void)
Definition ImageTexture.cpp:309

## Constructor & Destructor Documentation

## ◆ SoVRMLImageTexture()

SoVRMLImageTexture::SoVRMLImageTexture | ( | void |  | ) |

Constructor.

## ◆ ~SoVRMLImageTexture()

SoVRMLImageTexture::~SoVRMLImageTexture | ( |  | ) |
| protectedvirtual

Destructor.

## Member Function Documentation

## ◆ getClassTypeId()

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

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

## ◆ getTypeId()

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

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

Reimplemented from SoVRMLTexture.

## ◆ getFieldDataPtr()

const SoFieldData ** SoVRMLImageTexture::getFieldDataPtr | ( | void |  | ) |
| staticprotected

This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.
Returns the SoFieldData class which holds information about fields in this node.

## ◆ getFieldData()

const SoFieldData * SoVRMLImageTexture::getFieldData | ( | void |  | ) | const
| protectedvirtual

Returns a pointer to the class-wide field data storage object for this instance. If no fields are present, returns `NULL`.

Reimplemented from SoVRMLTexture.

## ◆ initClass()

void SoVRMLImageTexture::initClass | ( | void |  | ) |
| static

## ◆ setDelayFetchURL()

void SoVRMLImageTexture::setDelayFetchURL | ( | const SbBool | onoff | ) |
| static

Sets whether the image loading is delayed until the first time the image is needed, or if the image is loaded immediately when the url field is changed/set. Default value is TRUE.

## ◆ setPrequalifyFileCallBack()

void SoVRMLImageTexture::setPrequalifyFileCallBack | ( | VRMLPrequalifyFileCallback * | cb,
|  | void * | closure )
| static

Sets the prequalify callback for ImageTexture nodes. This is a callback that will be called when an image is about to be read.

## ◆ allowPrequalifyFile()

void SoVRMLImageTexture::allowPrequalifyFile | ( | SbBool | enable | ) |

Enable prequalify file loading.

## ◆ doAction()

void SoVRMLImageTexture::doAction | ( | SoAction * | action | ) |
| virtual

This function performs the typical operation of a node for any action.

Reimplemented from SoNode.

## ◆ GLRender()

void SoVRMLImageTexture::GLRender | ( | SoGLRenderAction * | action | ) |
| virtual

Action method for the SoGLRenderAction.

This is called during rendering traversals. Nodes influencing the rendering state in any way or want to throw geometry primitives at OpenGL override this method.

Reimplemented from SoVRMLTexture.

## ◆ callback()

void SoVRMLImageTexture::callback | ( | SoCallbackAction * | action | ) |
| virtual

Action method for SoCallbackAction.

Simply updates the state according to how the node behaves for the render action, so the application programmer can use the SoCallbackAction for extracting information about the scene graph.

Reimplemented from SoNode.

## ◆ rayPick()

void SoVRMLImageTexture::rayPick | ( | SoRayPickAction * | action | ) |
| virtual

Action method for SoRayPickAction.

Checks the ray specification of the action and tests for intersection with the data of the node.

Nodes influencing relevant state variables for how picking is done also override this method.

Reimplemented from SoNode.

## ◆ setImage()

void SoVRMLImageTexture::setImage | ( | const SbImage & | image | ) |

Set the image data for this node. Can be used by the prequalify callback to set the data in the node.

## ◆ getImage()

const SbImage * SoVRMLImageTexture::getImage | ( | void |  | ) | const

Returns the texture image.

## ◆ setImageDataMaxAge()

void SoVRMLImageTexture::setImageDataMaxAge | ( | const uint32_t | maxage | ) |
| static

This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.

## ◆ readInstance()

SbBool SoVRMLImageTexture::readInstance | ( | SoInput * | in,
|  | unsigned short | flags )
| protectedvirtual

This method is mainly intended for internal use during file import operations.

It reads a definition of an instance from the input stream in. The input stream state points to the start of a serialized / persistent representation of an instance of this class type.

`TRUE` or `FALSE` is returned, depending on if the instantiation and configuration of the new object of this class type went OK or not. The import process should be robust and handle corrupted input streams by returning `FALSE`.

flags is used internally during binary import when reading user extension nodes, group nodes or engines.

Reimplemented from SoNode.

## ◆ getReadStatus()

int SoVRMLImageTexture::getReadStatus | ( | void |  | ) | const
| protected

Returns the read status.

## ◆ setReadStatus()

void SoVRMLImageTexture::setReadStatus | ( | int | status | ) |
| protected

Sets the read status.

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

- SoVRMLImageTexture.h
- ImageTexture.cpp