--- name: "SoVRMLImageTexture" section: "3" platform: "linux" package: "coin" version: "1:4.0.10-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/SoVRMLImageTexture" --- # SoVRMLImageTexture(3) The SoVRMLImageTexture class is used for mapping a texture file onto geometry. ## NAME SoVRMLImageTexture - The **SoVRMLImageTexture** class is used for mapping a texture file onto geometry. ## SYNOPSIS \#include \ Inherits **SoVRMLTexture**. ### 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 #include #include #include #include #include #include #include #include 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(); } ``` ## Constructor & Destructor Documentation ### SoVRMLImageTexture::SoVRMLImageTexture (void ) *Constructor.* ### SoVRMLImageTexture::~SoVRMLImageTexture () \[protected\], \[virtual\] *Destructor.* ## Member Function Documentation ### SoType SoVRMLImageTexture::getClassTypeId (void ) \[static\] *This static method returns the* **SoType** *object associated with objects of this class.* ### 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***.* ### const SoFieldData \*\* SoVRMLImageTexture::getFieldDataPtr (void ) \[static\], \[protected\] *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.* ### const SoFieldData \* SoVRMLImageTexture::getFieldData (void ) const \[protected\], \[virtual\] *Returns a pointer to the class-wide field data storage object for this instance. If no fields are present, returns* NULL*.* *Reimplemented from* **SoVRMLTexture***.* ### void SoVRMLImageTexture::initClass (void ) \[static\] ### 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.* ### 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.* ### void SoVRMLImageTexture::allowPrequalifyFile (SbBool enable) *Enable prequalify file loading.* ### void SoVRMLImageTexture::doAction (SoAction \* action) \[virtual\] *This function performs the typical operation of a node for any action.* *Reimplemented from* **SoNode***.* ### 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***.* ### 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***.* ### 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***.* ### 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.* ### const SbImage \* SoVRMLImageTexture::getImage (void ) const *Returns the texture image.* ### 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.*\ ### SbBool SoVRMLImageTexture::readInstance (SoInput \* in, unsigned short flags) \[protected\], \[virtual\] *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***.* ### int SoVRMLImageTexture::getReadStatus (void ) const \[protected\] *Returns the read status.* ### void SoVRMLImageTexture::setReadStatus (int status) \[protected\] *Sets the read status.* ## Author *Generated automatically by Doxygen for Coin from the source code.*