SoText2(3)

📦 version 2.5.0, in fedora 43, fedora 44

🌸 NAME 🌸

hiii bestie, welcome to the SoText2(3) page from the Library Functions Manual 💖

So basically: SoText2 — the SoText2 class is a node type for visualizing 2D text aligned with the camera plane. that's it, that's the whole vibe. 2D text. stuck to the camera plane. iconic behavior honestly ✨

✨ SYNOPSIS ✨

#include <Inventor/nodes/SoText2.h>

Inherits SoShape. yes queen, she's part of the SoShape family tree 🫶

🎀 Public Types 🎀

enum Justification { LEFT = 1, RIGHT, CENTER } — the three ways your text can line up: LEFT, RIGHT, or CENTER. pick your fighter 💅

Public Types inherited from `SoShape`

enum TriangleShape { TRIANGLE_STRIP, TRIANGLE_FAN, TRIANGLES, POLYGON, QUADS, QUAD_STRIP, POINTS, LINES, LINE_STRIP } — all the shapes SoShape knows how to serve

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 } — every node-type bit flag, spelled out with its exact hex value, no skips

🌈 Public Member Functions 🌈

virtual SoType getTypeId (void) const — grabs the type id for this instance
SoText2 (void) — the constructor, aka the birth of your text node 🐣
virtual void GLRender (SoGLRenderAction *action) — renders the thing
virtual void rayPick (SoRayPickAction *action) — handles ray picking
virtual void getPrimitiveCount (SoGetPrimitiveCountAction *action) — reports how many primitives we're working with

Public Member Functions inherited from `SoShape`

virtual SbBool affectsState (void) const — does this node affect state? asking the real questions
virtual void notify (SoNotList *nl) — the notification hook
virtual void getBoundingBox (SoGetBoundingBoxAction *action) — computes the bounding box
virtual void callback (SoCallbackAction *action) — the callback traversal hook
const SoBoundingBoxCache * getBoundingBoxCache (void) const — hands you the bounding box cache

Public Member Functions inherited from `SoNode`

void setOverride (const SbBool state) — flips override mode on or off
SbBool isOverride (void) const — are we overridden rn?
void setNodeType (const NodeType type) — sets the node type
NodeType getNodeType (void) const — reads the node type back out
virtual SoNode * copy (SbBool copyconnections=0) const — makes a copy; pass copyconnections=0 by default
virtual void doAction (SoAction *action) — runs an action
virtual void GLRenderBelowPath (SoGLRenderAction *action) — the below-path GL render
virtual void GLRenderInPath (SoGLRenderAction *action) — the in-path GL render
virtual void GLRenderOffPath (SoGLRenderAction *action) — the off-path GL render
virtual void getMatrix (SoGetMatrixAction *action) — the matrix getter
virtual void handleEvent (SoHandleEventAction *action) — event handling, go off
virtual void pick (SoPickAction *action) — picking behavior
virtual void search (SoSearchAction *action) — the search action
virtual void write (SoWriteAction *action) — the write action
virtual void audioRender (SoAudioRenderAction *action) — yes, audio rendering is a whole thing
virtual void grabEventsSetup (void) — sets up event grabbing
virtual void grabEventsCleanup (void) — cleans up event grabbing
virtual void startNotify (void) — kicks off notification
uint32_t getNodeId (void) const — your node's id number
virtual SoChildList * getChildren (void) const — the children list pointer
virtual void writeInstance (SoOutput *out) — writes this instance out
virtual SoNode * addToCopyDict (void) const — adds itself to the copy dictionary
virtual void copyContents (const SoFieldContainer *from, SbBool copyconnections) — copies contents over from another container
virtual SoFieldContainer * copyThroughConnection (void) const — copies through a connection

Public Member Functions inherited from `SoFieldContainer`

void setToDefaults (void) — resets everything to defaults
SbBool hasDefaultValues (void) const — still at default values or nah?
SbBool fieldsAreEqual (const SoFieldContainer *container) const — compares fields with another container
void copyFieldValues (const SoFieldContainer *container, SbBool copyconnections=0) — copies field values over; copyconnections=0 by default
SbBool set (const char *const fielddata) — sets from a field data string
void get (SbString &fielddata) — pulls the field data out
virtual int getFields (SoFieldList &l) const — fills a list with the fields
virtual int getAllFields (SoFieldList &l) const — literally all of them
virtual SoField * getField (const SbName &name) const — look up a field by name
virtual SoField * getEventIn (const SbName &name) const — look up an event-in by name
virtual SoField * getEventOut (const SbName &name) const — look up an event-out by name
SbBool getFieldName (const SoField *const field, SbName &name) const — get the name of a given field
SbBool enableNotify (const SbBool flag) — toggles notification
SbBool isNotifyEnabled (void) const — is notification on?
SbBool set (const char *fielddata, SoInput *in) — the SoInput flavor of set
void get (SbString &fielddata, SoOutput *out) — the SoOutput flavor of get
virtual SbBool validateNewFieldValue (SoField *field, void *newval) — checks a new field value is valid
virtual void addWriteReference (SoOutput *out, SbBool isfromfield=0) — adds a write reference; isfromfield=0 by default
SbBool getIsBuiltIn (void) const — is it built in?
void setUserData (void *userdata) const — attaches user data
void * getUserData (void) const — grabs that user data back

Public Member Functions inherited from `SoBase`

void ref (void) const — bumps the reference count
void unref (void) const — drops the reference count
void unrefNoDelete (void) const — unref but don't delete
int32_t getRefCount (void) const — how many refs we holding
void touch (void) — touches it, classic
SbBool isOfType (SoType type) const — type check
virtual SbName getName (void) const — what's my name
virtual void setName (const SbName &newname) — renames it
void addAuditor (void *const auditor, const SoNotRec::Type type) — adds an auditor
void removeAuditor (void *const auditor, const SoNotRec::Type type) — removes an auditor
const SoAuditorList & getAuditors (void) const — the whole auditor list
SbBool shouldWrite (void) — should this be written?
void assertAlive (void) const — asserts the object is alive, very dramatic of it

💜 Static Public Member Functions 💜

static SoType getClassTypeId (void) — the class-level type id
static void initClass (void) — initializes the class

Static Public Member Functions inherited from `SoShape`

static SoType getClassTypeId (void) — class type id, SoShape edition
static void initClass (void) — init the class
static void getScreenSize (SoState *const state, const SbBox3f &boundingbox, SbVec2s &rectsize) — computes screen size from a bounding box
static float getDecimatedComplexity (SoState *state, float complexity) — returns the decimated complexity value

Static Public Member Functions inherited from `SoNode`

static uint32_t getCompatibilityTypes (const SoType &nodetype) — compatibility type bits for a node type
static SoType getClassTypeId (void) — class type id
static SoNode * getByName (const SbName &name) — find a node by name
static int getByName (const SbName &name, SoNodeList &l) — find nodes by name into a list
static void initClass (void) — init the class
static void initClasses (void) — init all the classes
static uint32_t getNextNodeId (void) — hands out the next node id
static int getActionMethodIndex (const SoType type) — the action method index for a type
static void getBoundingBoxS (SoAction *action, SoNode *node) — the static bounding box entry point
static void GLRenderS (SoAction *action, SoNode *node) — the static GL render entry point
static void callbackS (SoAction *action, SoNode *node) — static callback entry point
static void getMatrixS (SoAction *action, SoNode *node) — static matrix entry point
static void handleEventS (SoAction *action, SoNode *node) — static event handling entry point
static void pickS (SoAction *action, SoNode *node) — static pick entry point
static void rayPickS (SoAction *action, SoNode *node) — static ray pick entry point
static void searchS (SoAction *action, SoNode *node) — static search entry point
static void writeS (SoAction *action, SoNode *node) — static write entry point
static void audioRenderS (SoAction *action, SoNode *node) — static audio render entry point
static void getPrimitiveCountS (SoAction *action, SoNode *node) — static primitive count entry point

Static Public Member Functions inherited from `SoFieldContainer`

static void initClass (void) — init the class
static SoType getClassTypeId (void) — class type id
static void initCopyDict (void) — sets up the copy dictionary
static void addCopy (const SoFieldContainer *orig, const SoFieldContainer *copy) — registers a copy pair
static SoFieldContainer * checkCopy (const SoFieldContainer *orig) — checks the copy dictionary
static SoFieldContainer * findCopy (const SoFieldContainer *orig, const SbBool copyconnections) — finds a copy for an original
static void copyDone (void) — wraps up copying

Static Public Member Functions inherited from `SoBase`

static void initClass (void) — init the class
static SoType getClassTypeId (void) — class type id
static void addName (SoBase *const base, const char *const name) — registers a name
static void removeName (SoBase *const base, const char *const name) — unregisters a name
static void incrementCurrentWriteCounter (void) — bumps the write counter
static void decrementCurrentWriteCounter (void) — drops the write counter
static SoBase * getNamedBase (const SbName &name, SoType type) — gets a named base of a given type
static int getNamedBases (const SbName &name, SoBaseList &baselist, SoType type) — collects named bases into a list
static SbBool read (SoInput *in, SoBase *&base, SoType expectedtype) — the static read entry point
static void setInstancePrefix (const SbString &c) — sets the instance prefix
static void setTraceRefs (SbBool trace) — turns reference tracing on or off
static SbBool getTraceRefs (void) — is ref tracing on?
static SbBool connectRoute (SoInput *in, const SbName &fromnodename, const SbName &fromfieldname, const SbName &tonodename, const SbName &tofieldname) — wires up a route
static SbBool readRoute (SoInput *in) — reads a route

🦋 Public Attributes 🦋

SoMFString string — the actual text field, it's a multi-string
SoSFFloat spacing — the spacing value, single float
SoSFEnum justification — which justification mode we're on

🌟 Protected Member Functions 🌟

virtual const SoFieldData * getFieldData (void) const — returns the field data
virtual ~SoText2 () — the destructor
virtual void generatePrimitives (SoAction *action) — generates the primitives
virtual void computeBBox (SoAction *action, SbBox3f &box, SbVec3f &center) — computes the bounding box and center

Protected Member Functions inherited from `SoShape`

SoShape (void) — the constructor
virtual ~SoShape () — the destructor
float getComplexityValue (SoAction *action) — returns the complexity value
virtual SbBool shouldGLRender (SoGLRenderAction *action) — should we render this?
void beginSolidShape (SoGLRenderAction *action) — starts a solid shape
void endSolidShape (SoGLRenderAction *action) — ends a solid shape
void GLRenderBoundingBox (SoGLRenderAction *action) — renders the bounding box
SbBool shouldPrimitiveCount (SoGetPrimitiveCountAction *action) — should we count primitives?
SbBool shouldRayPick (SoRayPickAction *const action) — should we ray pick?
void computeObjectSpaceRay (SoRayPickAction *const action) — computes the object space ray
void computeObjectSpaceRay (SoRayPickAction *const action, const SbMatrix &matrix) — same thing but with a matrix
virtual SoDetail * createTriangleDetail (SoRayPickAction *action, const SoPrimitiveVertex *v1, const SoPrimitiveVertex *v2, const SoPrimitiveVertex *v3, SoPickedPoint *pp) — builds triangle detail
virtual SoDetail * createLineSegmentDetail (SoRayPickAction *action, const SoPrimitiveVertex *v1, const SoPrimitiveVertex *v2, SoPickedPoint *pp) — builds line segment detail
virtual SoDetail * createPointDetail (SoRayPickAction *action, const SoPrimitiveVertex *v, SoPickedPoint *pp) — builds point detail
void invokeTriangleCallbacks (SoAction *const action, const SoPrimitiveVertex *const v1, const SoPrimitiveVertex *const v2, const SoPrimitiveVertex *const v3) — fires the triangle callbacks
void invokeLineSegmentCallbacks (SoAction *const action, const SoPrimitiveVertex *const v1, const SoPrimitiveVertex *const v2) — fires the line segment callbacks
void invokePointCallbacks (SoAction *const action, const SoPrimitiveVertex *const v) — fires the point callbacks
void beginShape (SoAction *const action, const TriangleShape shapetype, SoDetail *const detail=NULL) — opens a shape; detail defaults to NULL
void shapeVertex (const SoPrimitiveVertex *const v) — feeds a shape vertex
void endShape (void) — closes the shape
void generateVertex (SoPrimitiveVertex *const pv, const SbVec3f &point, const SbBool useTexFunc, const SoTextureCoordinateElement *const tce, const float s, const float t, const SbVec3f &normal) — generates a vertex, the s/t version
void generateVertex (SoPrimitiveVertex *const pv, const SbVec3f &point, const SbBool useTexFunc, const SoTextureCoordinateElement *const tce, const float s, const float t, const float r, const SbVec3f &normal) — generates a vertex, the s/t/r version
SbBool startVertexArray (SoGLRenderAction *action, const SoCoordinateElement *coords, const SbVec3f *pervertexnormals, const SbBool texpervertex, const SbBool colorpervertex) — starts the vertex array
void finishVertexArray (SoGLRenderAction *action, const SbBool vbo, const SbBool normpervertex, const SbBool texpervertex, const SbBool colorpervertex) — finishes the vertex array

Protected Member Functions inherited from `SoNode`

SoNode (void) — constructor
virtual ~SoNode () — destructor
virtual SbBool readInstance (SoInput *in, unsigned short flags) — reads an instance

Protected Member Functions inherited from `SoFieldContainer`

SoFieldContainer (void) — constructor
~SoFieldContainer () — destructor

Protected Member Functions inherited from `SoBase`

SoBase (void) — constructor
virtual ~SoBase () — destructor
virtual void destroy (void) — destroy it
SbBool hasMultipleWriteRefs (void) const — multiple write refs or not
SbBool writeHeader (SoOutput *out, SbBool isgroup, SbBool isengine) const — writes the header
void writeFooter (SoOutput *out) const — writes the footer
virtual const char * getFileFormatName (void) const — returns the file format name

⭐ Static Protected Member Functions ⭐

static const SoFieldData ** getFieldDataPtr (void) — pointer to the field data pointer

Static Protected Member Functions inherited from `SoShape`

static const SoFieldData ** getFieldDataPtr (void) — same deal, inherited from SoShape

okay bestie that's the whole class tour for part one 💅 literally every flag, every inherited function, every default value, all of it. and there's more coming, so don't go anywhere 🫶✨

🫶 Static Protected Member Functions inherited from `SoNode`

static const SoFieldData ** getFieldDataPtr (void) — a pointer-to-pointer of field data. yes bestie, that's the whole description, the source really said that and nothing else 💀
static void setNextActionMethodIndex (int index) — sets the next action method index, taking an index. no extra lore given.
static int getNextActionMethodIndex (void) — gets it back. that's it, that's the tea.
static void incNextActionMethodIndex (void) — increments it. zero notes provided, it's giving mysterious 💅
static void setCompatibilityTypes (const SoType &nodetype, const uint32_t bitmask) — takes a nodetype and a bitmask. the docs left it at that, so we're leaving it at that.

🌸 Static Protected Member Functions inherited from `SoBase`

static uint32_t getCurrentWriteCounter (void) — returns a uint32_t. no description in the original, just vibes ✨
static void staticDataLock (void) — locks the static data. go off.
static void staticDataUnlock (void) — unlocks it. a matched set, iconic.

🦋 Friends

class SoText2P — officially a friend of this class. bestie privileges granted 🫶

👑 Additional Inherited Members

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

💖 Detailed Description

okay so SoText2 is the node type for visualizing 2D text that stays aligned with the camera plane. it's the "text that just sits there and faces you" girlie 💅

here's the thing though, and this is important: SoText2 text is not scaled according to the distance from the camera, and it is not influenced by rotation or scaling the way 3D primitives are. if those are properties you actually want the text to have, you should use an SoText3 or SoAsciiText node instead. periodt.

also note that even though the size of the 2D text isn't influenced by the distance from the camera, the text is still subject to the usual rules with regard to the depthbuffer, so it will be obscured by graphics laying in front of it. no cap, it can get hidden. 😭

the text gets positioned according to the current transformation. here's the geometry tea:

the x origin of the text is the first pixel of the leftmost character of the text.
the y origin of the text is the baseline of the first line of text — and the baseline is that imaginary line all your upper case characters are standing on 🧚

the size of the fonts on screen is decided from the SoFont::size field of a preceding SoFont-node in the scene graph, which specifies the size in pixel dimensions. this value sets the approximate vertical dimension of the letters. and if you don't use any SoFont-nodes at all? the default value is 10.

🚨 rendering performance, listen up

this is the part where i grab you by the shoulders. since the positioning and rendering of an SoText2 node depends on the current viewport and camera, having SoText2 nodes in the scene graph will lead to a cache dependency on the previously encountered SoCamera-node. and that can have severe influence on rendering performance, because if the camera is above the SoText2's nearest parent SoSeparator, that SoSeparator will not be able to cache the geometry under it. 💀

(and it gets even worse if the SoSeparator::renderCaching flag is explicitly set to ON, because then the SoSeparator node will continuously generate and destruct the same cache as the camera moves. not the move, bestie.)

so the correct way to do this: SoText2 nodes are best positioned under their own SoSeparator node, outside areas in the scene graph that otherwise contain static geometry. protect your frame rate 🫶

also — and this is a sneaky one — SoText2 nodes cache the ids and positions of each glyph bitmap used to render a string. which means a USE of a DEF'ed SoText2 node, with a different font, will be noticeably slower than just using two separate SoText2 nodes, one for each font, because it'll have to recalculate glyph bitmap ids and positions for each call to GLrender(). two nodes > one reused node here, fr fr.

and finally: SoScale nodes can not be used to influence the dimensions of the rendering output of SoText2 nodes. don't try it, it's not giving what you think it's giving 🙈

📄 FILE FORMAT/DEFAULTS

Text2 {
    string ""
    spacing 1
    justification LEFT
}

👀 See also

SoFont, SoFontStyle, SoText3, SoAsciiText

🌈 Member Enumeration Documentation

`enum SoText2::Justification`

this enum contains the various options for how the horizontal text layout of the text should be done. the valid values are LEFT, RIGHT and CENTER. pick your fighter ✨

🎀 Constructor & Destructor Documentation

`SoText2::SoText2 (void )`

Constructor. that's the whole description, she's a simple girlie 💖

References: justification, SoText2(), and spacing.
Referenced by: getFieldData(), and SoText2().

`SoText2::~SoText2 () [protected], [virtual]`

Destructor. short and sweet, no notes 🌸

💜 Member Function Documentation

`SoType SoText2::getTypeId (void ) const [virtual]`

returns the type identification of an object derived from a class inheriting SoBase. this is used for run-time type checking and "downward" casting. iykyk 🫶

usage example, verbatim, do not touch:

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 info on writing Coin extensions, see the class documentation of the toplevel superclasses for the various class groups.