SoTexture2(3)

📦 version 2.5.0, in fedora 43, fedora 44

💖 SoTexture2 💖

okay bestie, welcome to the glow-up zone ✨ this is the SoTexture2(3) page from the Library Functions Manual, and it's lowkey one of the most iconic nodes in the whole scenegraph. sit down, hydrate, and let's get into it 🫶

✨ NAME ✨

SoTexture2 — the class you use to map a 2D texture onto all the geometry that comes after it in the scenegraph. like, you drop it in, and everything downstream gets the lewk. it's giving "I'm the vibe-setter, everything after me matches my energy" 💅

🌸 SYNOPSIS 🌸

#include <Inventor/nodes/SoTexture2.h>

Inherits SoNode. so yeah, she's a node, she has all the node powers, no cap 🎀

Public Types

  • enum Model — MODULATE = SoTextureImageElement::MODULATE, DECAL = SoTextureImageElement::DECAL, BLEND = SoTextureImageElement::BLEND, REPLACE = SoTextureImageElement::REPLACE
  • enum Wrap — REPEAT = SoTextureImageElement::REPEAT, CLAMP = SoTextureImageElement::CLAMP

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

🦋 Public Member Functions 🦋

the main character lineup, bestie:

  • virtual SoType getTypeId (void) const
  • SoTexture2 (void) — the constructor, she's here, she's ready
  • virtual void doAction (SoAction *action)
  • virtual void GLRender (SoGLRenderAction *action)
  • virtual void callback (SoCallbackAction *action)
  • virtual void rayPick (SoRayPickAction *action)

Public Member Functions inherited from SoNode

the family tree. all of this comes with the node package, no extra charge 💖

  • void setOverride (const SbBool state)
  • SbBool isOverride (void) const
  • void setNodeType (const NodeType type)
  • NodeType getNodeType (void) const
  • virtual SoNode * copy (SbBool copyconnections=0) 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)
  • uint32_t 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=0)
  • 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 *in)
  • void get (SbString &fielddata, SoOutput *out)
  • virtual SbBool validateNewFieldValue (SoField *field, void *newval)
  • virtual void addWriteReference (SoOutput *out, SbBool isfromfield=0)
  • SbBool getIsBuiltIn (void) 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
  • 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 SbBool readImage (const SbString &fname, int &w, int &h, int &nc, unsigned char *&bytes)

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)
  • static void initClasses (void)
  • static uint32_t 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)
  • static SoType getClassTypeId (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)
  • static SoType getClassTypeId (void)
  • 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 *in, SoBase *&base, SoType expectedtype)
  • static void setInstancePrefix (const SbString &c)
  • static void setTraceRefs (SbBool trace)
  • static SbBool getTraceRefs (void)
  • static SbBool connectRoute (SoInput *in, const SbName &fromnodename, const SbName &fromfieldname, const SbName &tonodename, const SbName &tofieldname)
  • static SbBool readRoute (SoInput *in)

👑 Public Attributes 👑

these are the fields, bestie, the actual lewk of the node ✨

  • SoSFString filename
  • SoSFImage image
  • SoSFEnum wrapS
  • SoSFEnum wrapT
  • SoSFEnum model
  • SoSFColor blendColor

🧚 Protected Member Functions 🧚

for the girlies working on the inside, iykyk:

  • virtual const SoFieldData * getFieldData (void) const
  • virtual ~SoTexture2 ()
  • virtual SbBool readInstance (SoInput *in, unsigned short flags)
  • virtual void notify (SoNotList *list)
  • int getReadStatus (void)
  • void setReadStatus (int s)

Protected Member Functions inherited from SoNode

  • SoNode (void)
  • virtual ~SoNode ()

Protected Member Functions inherited from SoFieldContainer

  • SoFieldContainer (void)
  • ~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

💜 Static Protected Member Functions 💜

  • 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)

🎀 Friends 🎀

the inner circle. very exclusive. very "you wouldn't get it" 🫶

  • class SoFieldData

⭐ Additional Inherited Members ⭐

the bonus lore, still part of the canon:

Protected Types inherited from SoBase

  • enum BaseFlags — IS_ENGINE = 0x01, IS_GROUP = 0x02

Protected Attributes inherited from SoNode

  • uint32_t uniqueId

Protected Attributes inherited from SoFieldContainer

  • SbBool isBuiltIn

Static Protected Attributes inherited from SoNode

  • static uint32_t nextUniqueId = 0
  • static int nextActionMethodIndex = 0

okay and that's the whole header/synopsis situation laid out for you 💅 no details dropped, every single function, enum value, field and friend accounted for. more parts are coming so don't go anywhere bestie, we're just getting started 🌸

🌸 Detailed Description 🌸

okay bestie, here's the whole vibe of SoTexture2: this class is the way you slap a 2D texture onto all the geometry that comes after it in the scenegraph. it's giving sticker book energy for 3D. 💅

Shape nodes that live within the scope of your SoTexture2 nodes — and by that i mean below the same SoSeparator and over on the righthand side of the SoTexture2 — get the texture applied, and how it gets applied depends on each shape type's own individual characteristics. so like, if you wanna know the specifics of how textures land on each one, go read the docs for the various shape types (SoFaceSet, SoCube, SoSphere, etc etc). they each do their own thing, no cap.

For a super simple usage example, check the class documentation for SoSFImage. 🎀

okay so here's a very real problem that a LOT of programs with VRML or Inventor export support have: they export the same texture file several times, but as different nodes. and bestie. that is a crime against your GPU. it causes 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/nodes/SoSeparator.h>
#include <Inventor/nodes/SoTexture2.h>
#include <Inventor/SoDB.h>
#include <Inventor/SoInput.h>
#include <Inventor/SoOutput.h>

int main(int argc, char ** argv)
{
  if (argc < 2) return -1;
  SoDB::init();

  SoInput in;
  if (!in.openFile(argv[1])) return -1;

  SoSeparator * root = SoDB::readAll(&in);
  if (!root) return -1;
  root->ref();

  SoSearchAction sa;
  sa.setType(SoTexture2::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(SoTexture2::getClassTypeId())) {
      SoTexture2 * tex = (SoTexture2*) p->getTail();
      if (tex->filename.getValue().getLength()) {
        SbName name = tex->filename.getValue().getString();
        unsigned long key = (unsigned long) ((void*) name.getString());
        void * tmp;
        if (!namedict.find(key, tmp)) {
          // new texture. just insert into list
          (void) namedict.enter(key, tex);
        }
        else if (tmp != (void*) tex) { // replace with node found in dict
          SoGroup * parent = (SoGroup*) p->getNodeFromTail(1);
          int idx = p->getIndexFromTail(0);
          parent->replaceChild(idx, (SoNode*) tmp);
        }
      }
    }
  }
  sa.reset();

  // output fixed scene to stdout
  SoOutput out;
  SoWriteAction wa(&out);
  wa.apply(root);
  root->unref();
}

✨ moving on to the next scenario ✨ — when you're working with Inventor files, you'll often want to embed external texture image files into the Inventor files themselves. Here's a minimal, stand-alone example showing how to do that by calling SoField::touch() on the SoTexture2::image fields before you export the scenegraph:

#include <Inventor/SoDB.h>
#include <Inventor/nodes/SoSeparator.h>
#include <Inventor/nodes/SoTexture2.h>
#include <Inventor/actions/SoSearchAction.h>
#include <Inventor/actions/SoWriteAction.h>

int
main(void)
{
  SoDB::init();

  SoInput in;
  SoSeparator * root = SoDB::readAll(&in);
  if (!root) { exit(1); }

  root->ref();

  SoSearchAction searchaction;
  searchaction.setType(SoTexture2::getClassTypeId());
  searchaction.setSearchingAll(TRUE);
  searchaction.setInterest(SoSearchAction::ALL);

  searchaction.apply(root);

  const SoPathList & pl = searchaction.getPaths();
  for (int i=0; i < pl.getLength(); i++) {
    SoFullPath * fp = (SoFullPath *)pl[i];
    SoTexture2 * tex = (SoTexture2 *)fp->getTail();
    assert(tex->getTypeId() == SoTexture2::getClassTypeId());
    tex->image.touch();
  }

  SoWriteAction wa;
  wa.apply(root);

  root->unref();

  return 0;
}

Run the example by piping the iv-file you want do texture-embedding on from stdin, e.g. like this:

$ ./test < input.iv

FILE FORMAT/DEFAULTS:

Texture2 {
    filename ""
    image 0 0 0
    wrapS REPEAT
    wrapT REPEAT
    model MODULATE
    blendColor 0 0 0
    enableCompressedTexture FALSE
}

🦋 Member Enumeration Documentation 🦋

💜 enum SoTexture2::Model

Texture mapping model — this is the little setting that decides how the texturemap "merges" with the object it's mapped onto. and yes, the quotes around "merge" are load-bearing. 💅

Enumerator

  • MODULATE — texture color gets multiplied by the polygon color. the result will be Phong shaded (as long as the light model is PHONG). ⭐
  • DECAL — the texture image straight-up overwrites polygon shading. textured pixels will not be Phong shaded. heads up tho: it has undefined behaviour for grayscale and grayscale-alpha textures. 😭
  • BLEND — this model is normally used with monochrome textures (aka textures with one or two components). the first component, the intensity, is then used to blend between the shaded color of the polygon and the SoTexture2::blendColor. ✨
  • REPLACE — the texture image overwrites polygon shading. textured pixels will not be Phong shaded. it supports grayscale and grayscale alpha textures. this feature requires OpenGL 1.1. if OpenGL version < 1.1 is detected, MODULATE will be used instead. 🫶
⚠️ bestie listen: using this texture model will make your Inventor files incompatible with older versions of Coin and Inventor. you need Coin >= 2.2 or TGS Inventor 4.0 to load Inventor files that use the REPLACE texture model. no cap. Since — Coin 2.2 TGS Inventor 4.0

🌈 enum SoTexture2::Wrap

Enumeration of wrapping strategies which can be used when the texturemap doesn't cover the full extent of the geometry. basically: what happens at the edges, babes. 🎀

Enumerator

  • REPEAT — repeat texture when coordinate is not between 0 and 1. 🔁
  • CLAMP — clamp coordinate between 0 and 1. 📌

👑 Constructor & Destructor Documentation 👑

💖 SoTexture2::SoTexture2 (void )

Constructor. the main character arrives. ✨

References BLEND, blendColor, CLAMP, DECAL, filename, image, model, MODULATE, REPEAT, REPLACE, SoTexture2(), wrapS, and wrapT.

Referenced by getFieldData(), and SoTexture2().

🎀 SoTexture2::~SoTexture2 () [protected], [virtual]

Destructor. Frees up internal resources used to store texture image data. it's giving responsible memory management, we love to see it. 💅

✨ MEMBER FUNCTION DOCUMENTATION ✨

SoType SoTexture2::getTypeId (void ) const [virtual]

Okay bestie, this one hands you the type ID of any object that descends from SoBase — it's the whole vibe check for run-time type checking and "downward" casting. 🔍

Usage example, and yes you can literally copy-paste this:

void foo(SoNode * node)
{
  if (node->getTypeId() == SoFile::getClassTypeId()) {
    SoFile * filenode = (SoFile *)node;  // safe downward cast, knows the type
  }
  else if (node->getTypeId().isOfType(SoGroup::getClassTypeId())) {
    SoGroup * group = (SoGroup *)node;  // safe downward cast, knows the type
  }
}

For application programmers wanting to extend the library with new nodes, engines, nodekits, draggers or others: this method needs to be overridden in all subclasses. This is typically done as part of setting up the full type system for extension classes, which is usually accomplished by using the pre-defined macros available through for instance Inventor/nodes/SoSubNode.h (SO_NODE_INIT_CLASS and SO_NODE_CONSTRUCTOR for node classes), Inventor/engines/SoSubEngine.h (for engine classes) and so on.

For more information on writing Coin extensions, see the class documentation of the toplevel superclasses for the various class groups.

Implements SoBase.

const SoFieldData * SoTexture2::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 SoFieldContainer.

References SoTexture2().

void SoTexture2::doAction (SoAction * action) [virtual]

This function performs the typical operation of a node for any action. It's giving "do the thing" energy. ✨

Reimplemented from SoNode.

References SoAction::getState(), image, SoNode::isOverride(), model, and wrapT.

Referenced by callback(), and rayPick().

void SoTexture2::GLRender (SoGLRenderAction * action) [virtual]

Action method for the SoGLRenderAction. 👑

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

Reimplemented from SoNode.

References SoType::badType(), blendColor, SoAction::getState(), image, SoState::isCacheOpen(), SoNode::isOverride(), model, SoDebugError::postWarning(), wrapS, and wrapT.

void SoTexture2::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.

References doAction().

void SoTexture2::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 overrides this method.

Reimplemented from SoNode.

References doAction().

SbBool SoTexture2::readImage (const SbString & fname, int & w, int & h, int & nc, unsigned char *& bytes) [static]

Not implemented in Coin; should probably not have been public in the original SGI Open Inventor API. We'll consider to implement it if requested. 💀

That's literally it, no cap.

SbBool SoTexture2::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 / persistant 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.

References filename, SoReadError::post(), SoNode::readInstance(), and setReadStatus().

void SoTexture2::notify (SoNotList * l) [protected], [virtual]

Notifies all auditors for this instance when changes are made. 📣

Reimplemented from SoNode.

References filename, SoNotList::getLastField(), image, SoNode::notify(), wrapS, and wrapT.

int SoTexture2::getReadStatus (void ) [protected]

Returns read status. 1 for success, 0 for failure. ✅❌

void SoTexture2::setReadStatus (int s) [protected]

Sets read status. 🛠️

See also getReadStatus()

Referenced by readInstance().

✨ MEMBER DATA DOCUMENTATION ✨

SoSFString SoTexture2::filename

Texture filename, referring to a file on disk in a supported image bitmap format. 🖼️

By default contains an empty string, which means the texture will be fetched from SoTexture2::image and not from disk. (Specify either this field or use SoTexture2::image, not both.)

For reading texture image files from disk, Coin uses the "simage" library from Systems in Motion. This library must be installed for it to be possible to load any image files at all.

The set of image formats you can actually read with the simage library depends on how the simage library was built, as simage is again dependent on a few other low-level file import/export libraries (for instance for JPEG, GIF, TIFF and PNG support). To make sure all wanted formats are supported, you should build the simage library yourself.

The set of image formats guaranteed to be supported by simage is Targa (.tga), PIC (.pic), SGI RGB (.rgb, .bw) and XWD (.xwd).

For more information about the simage library, including download and build instructions, see the Coin www-pages.

Referenced by notify(), readInstance(), and SoTexture2().

SoSFImage SoTexture2::image

Inline image data. Defaults to contain an empty image. 🎨

See documentation of the SoSFImage class for a very detailed description of how the format specification for the image data is layed out, and what different image formats for color textures, semi-transparent textures, grayscale textures, etc etc, are supported.

Referenced by doAction(), GLRender(), notify(), and SoTexture2().

SoSFEnum SoTexture2::wrapS

Wrapping strategy for the S coordinate when the texturemap is narrower than the object to map onto. 🧵

Default value is SoTexture2::REPEAT.

Referenced by GLRender(), notify(), and SoTexture2().

SoSFEnum SoTexture2::wrapT

Wrapping strategy for the T coordinate when the texturemap is shorter than the object to map onto. 🧶

Default value is SoTexture2::REPEAT.

Referenced by doAction(), GLRender(), notify(), and SoTexture2().

SoSFEnum SoTexture2::model

Texturemapping model for how the texturemap is "merged" with the polygon primitives it is applied to. Default value is SoTexture2::MODULATE. 🧬

Referenced by doAction(), GLRender(), and SoTexture2().

SoSFColor SoTexture2::blendColor

Blend color. Used when SoTexture2::model is SoTexture2::BLEND. 🌈

Default color value is [0, 0, 0], black, which means no contribution to the blending is made.

Referenced by GLRender(), and SoTexture2().

✨ AUTHOR ✨

Generated automatically by Doxygen for Coin from the source code. 🤖

And that's a wrap, bestie! This iconic manual page is from Coin Version 2.5.0, page SoTexture2(3) — generated automatically by Doxygen for Coin from the source code. Slay. 💅✨

📦 where this page comes from