SoInput(3)

📦 version 2.5.0, in fedora 43, fedora 44

🦋 SoInput(3) — Library Functions Manual 🦋

okay so bestie, you're about to read the SoInput(3) page and it's giving file import abstraction realness. no cap. let's go 💅

✨ NAME ✨

SoInput — the SoInput class is an abstraction of file import functionality.

🌸 SYNOPSIS 🌸

#include <Inventor/SoInput.h>

💅 Public Member Functions 💅

  • SoInput (void)
  • SoInput (SoInput *dictIn)
  • SoProto * findProto (const SbName &name)
  • void addProto (SoProto *proto)
  • void pushProto (SoProto *proto)
  • SoProto * getCurrentProto (void) const
  • void popProto (void)
  • void addRoute (const SbName &fromnode, const SbName &fromfield, const SbName &tonode, const SbName &tofield)
  • SbBool checkISReference (SoFieldContainer *container, const SbName &fieldname, SbBool &readok)
  • virtual ~SoInput (void)
  • virtual void setFilePointer (FILE *newFP)
  • virtual SbBool openFile (const char *fileName, SbBool okIfNotFound=0)
  • virtual SbBool pushFile (const char *fileName)
  • virtual void closeFile (void)
  • virtual SbBool isValidFile (void)
  • virtual SbBool isValidBuffer (void)
  • virtual FILE * getCurFile (void) const
  • virtual const char * getCurFileName (void) const
  • virtual void setBuffer (void *bufpointer, size_t bufsize)
  • void setStringArray (const char *strings[])
  • virtual size_t getNumBytesRead (void) const
  • virtual SbString getHeader (void)
  • virtual float getIVVersion (void)
  • virtual SbBool isBinary (void)
  • virtual SbBool get (char &c)
  • virtual SbBool getASCIIBuffer (char &c)
  • virtual SbBool getASCIIFile (char &c)
  • virtual SbBool readHex (uint32_t &l)
  • virtual SbBool read (char &c)
  • virtual SbBool read (char &c, SbBool skip)
  • virtual SbBool read (SbString &s)
  • virtual SbBool read (SbName &n, SbBool validIdent=0)
  • virtual SbBool read (int &i)
  • virtual SbBool read (unsigned int &i)
  • virtual SbBool read (short &s)
  • virtual SbBool read (unsigned short &s)
  • virtual SbBool read (float &f)
  • virtual SbBool read (double &d)
  • virtual SbBool readBinaryArray (unsigned char *c, int length)
  • virtual SbBool readBinaryArray (int32_t *l, int length)
  • virtual SbBool readBinaryArray (float *f, int length)
  • virtual SbBool readBinaryArray (double *d, int length)
  • SbBool readByte (int8_t &b)
  • SbBool readByte (uint8_t &b)
  • virtual SbBool eof (void) const
  • SbBool isFileVRML1 (void)
  • SbBool isFileVRML2 (void)
  • virtual void resetFilePointer (FILE *fptr)
  • virtual void getLocationString (SbString &string) const
  • virtual void putBack (const char c)
  • virtual void putBack (const char *str)
  • virtual void addReference (const SbName &name, SoBase *base, SbBool addToGlobalDict=1)
  • virtual void removeReference (const SbName &name)
  • virtual SoBase * findReference (const SbName &name) const

⭐ Static Public Member Functions ⭐

  • static void addDirectoryFirst (const char *dirName)
  • static void addDirectoryLast (const char *dirName)
  • static void addEnvDirectoriesFirst (const char *envVarName, const char *separator=': ')
  • static void addEnvDirectoriesLast (const char *envVarName, const char *separator=': ')
  • static void removeDirectory (const char *dirName)
  • static void clearDirectories (void)
  • static const SbStringList & getDirectories (void)
  • static void init (void)
  • static SbString getPathname (const char *const filename)
  • static SbString getPathname (const SbString &s)
  • static SbString getBasename (const char *const filename)
  • static SbString getBasename (const SbString &s)
  • static SbString searchForFile (const SbString &basename, const SbStringList &directories, const SbStringList &subdirectories)

🧚 Protected Member Functions 🧚

  • virtual SbBool popFile (void)
  • void setIVVersion (float version)
  • FILE * findFile (const char *fileName, SbString &fullName)
  • void initFile (FILE *newFP, const char *fileName, SbString *fullName, SbBool openedHere, SbDict *refDict=(SbDict *) NULL)
  • SbBool checkHeader (SbBool bValidateBufferHeader=0)
  • SbBool fromBuffer (void) const
  • SbBool skipWhiteSpace (void)
  • size_t freeBytesInBuf (void) const
  • SbBool readInteger (int32_t &l)
  • SbBool readUnsignedInteger (uint32_t &l)
  • SbBool readReal (double &d)
  • SbBool readUnsignedIntegerString (char *str)
  • int readDigits (char *str)
  • int readHexDigits (char *str)
  • int readChar (char *str, char charToRead)
  • SbBool makeRoomInBuf (size_t nBytes)
  • void convertShort (char *from, short *s)
  • void convertInt32 (char *from, int32_t *l)
  • void convertFloat (char *from, float *f)
  • void convertDouble (char *from, double *d)
  • void convertShortArray (char *from, short *to, int len)
  • void convertInt32Array (char *from, int32_t *to, int len)
  • void convertFloatArray (char *from, float *to, int len)
  • void convertDoubleArray (char *from, double *to, int len)
  • SbBool isFileURL (const char *url)
  • char * URLToFile (char *out_buf, const char *in_buf)
  • SbBool IsURL (const char *c_strng)

🌟 Static Protected Member Functions 🌟

  • static void setDirectories (SbStringList *dirs)

🫶 Friends 🫶

  • class SoDB
  • class SoInputP

👑 Detailed Description 👑

The SoInput class is an abstraction of file import functionality.

This class takes care of most of the chores of doing data import in Coin. It puts a layer of abstraction over the read operations to make it transparent for the rest of the Coin code whether or not we're reading from a file, from a memory buffer or from stdin.

SoInput also takes care of checking file validity, aswell as handling information about features in the various file formats which are supported.

Example usage:

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

  SoInput in;
  if (in.openFile("fab_model.iv")) {
    SoSeparator * root = SoDB::readAll(&in);
    if (root) {
      // Do stuff with the imported scene graph here
      // ...
      return 0;
    }
  }

  return 1;
}
⚠️ Important note: there are several public and protected methods which makes it possible to pass in or get returned FILE* structures in this class. Do not use these methods when the Coin library has been compiled as an MSWindows DLL, as passing FILE* instances back or forth to DLLs is dangerous and will most likely cause a crash. This is an intrinsic limitation for MSWindows DLLs.

This class supports one environment variable called COIN_SOINPUT_SEARCH_GLOBAL_DICT. When set to "1", the global dictionary is searched after the current file dictionary when resolving USE keywords. This makes it possible to reference nodes in other files. The reason for introducing this feature is that the SoFile node rereads the file whenever the name field changes. The first time the file is read, it's possible to reference nodes in the parent file, using the USE keyword. But, when the file is reread this is no longer possible, since the reading now starts at the SoFile node, with an empty dictionary.

🫶 See also 🫶

SoOutput, SoDB

🎀 Constructor & Destructor Documentation 🎀

SoInput::SoInput (void )

Constructor. If no filepointer is set, input will be read from stdin.

Referenced by getLocationString(), and SoInput().

SoInput::SoInput (SoInput *dictIn)

A constructor which copies the reference mappings from dictIn upon initialization.

References SoInput().

SoInput::~SoInput (void ) [virtual]

Destructor. Runs SoInput::closeFile() to close any open files.

References closeFile(), SbPList::getLength(), and SbPList::truncate().

🌈 Member Function Documentation 🌈

SoProto * SoInput::findProto (const SbName & name)

Searches for PROTO named name. This function will only return PROTOs that have been read by the current SoInput instance.

Since: Coin 2.3

void SoInput::addProto (SoProto * proto)

Adds a Proto which should be active in the current scope.

This function is an extension for Coin, and it is not available in the original SGI Open Inventor v2.1 API.

Since: Coin 2.0

Referenced by SoFieldData::read().

void SoInput::pushProto (SoProto * proto)

Pushed a Proto onto the Proto stack. The Proto stack is used during VRML2 file parsing.

This function is an extension for Coin, and it is not available in the original SGI Open Inventor v2.1 API.

See also: popProto()

Since: Coin 2.0

SoProto * SoInput::getCurrentProto (void ) const

Returns the Proto at the top of the Proto stack.

This function is an extension for Coin, and it is not available in the original SGI Open Inventor v2.1 API.

See also: pushProto()

Since: Coin 2.0

Referenced by addReference(), checkISReference(), findReference(), SoBase::readRoute(), and removeReference().

void SoInput::popProto (void )

Pops a Proto off the Proto stack.

This function is an extension for Coin, and it is not available in the original SGI Open Inventor v2.1 API.

See also: pushProto()

Since: Coin 2.0

void SoInput::addRoute (const SbName & fromnode, const SbName & fromfield, const SbName & tonode, const SbName & tofield)

Adds a ROUTE from /a fromnode's \fromfield, to tonode's tofield. This makes it possible to defines ROUTEs in files before the fromnode or tonode is parsed.

This function is an extension for Coin, and it is not available in the original SGI Open Inventor v2.1 API.

Since: Coin 2.0

Referenced by SoBase::readRoute().

SbBool SoInput::checkISReference (SoFieldContainer * container, const SbName & fieldname, SbBool & readok)

Checks if the next bytes in in is the IS keyword. Returns TRUE if the IS keyword was found, readok will be set to FALSE if some error occured while searching for the IS keyword.

This function is an extension for Coin, and it is not available in the original SGI Open Inventor v2.1 API.

Since: Coin 2.0

References getCurrentProto(), SbString::getString(), SoBase::isOfType(), putBack(), and read().

Referenced by SoField::read(), SoFieldData::read(), and SoFieldData::readFieldDescriptions().

void SoInput::setFilePointer (FILE * newFP) [virtual]

Uses the given file pointer as the input file. The input stack of files will be emptied first. Closing a file passed in by it's file pointer is the library user's responsibility.

⚠️ Important note: do not use this method when the Coin library has been compiled as an MSWindows DLL, as passing FILE* instances back or forth to DLLs is dangerous and will most likely cause a crash. This is an intrinsic limitation for MSWindows DLLs.

Note that it is not allowed to pass a FILE* to a gzip-compressed file under Mac OS X.

See also: openFile(), closeFile()

References closeFile().

SbBool SoInput::openFile (const char * fileName, SbBool okIfNotFound = 0) [virtual]

Open the given file, and make it the only one in the file stack. If okIfNotFound is FALSE, show a warning message if the file could not be opened.

Returns TRUE if file could be opened for reading, FALSE otherwise.

heads up bestie: even if ur file-opening attempt flops, this SoInput is not gonna quietly fall back to reading from stdin once you've called this method. no sneaky default for u 💅

See also: setFilePointer(), pushFile(), closeFile()

References: addDirectoryFirst(), closeFile(), findFile(), getPathname(), SbString::getString(), and SoReadError::post().

Referenced by: SoInteractionKit::readDefaultParts().

💖 SbBool SoInput::pushFile (const char * filename) [virtual] 💖

Pushes a brand-new file on top of the stack, like stacking another pancake on the pile 🥞✨. Every read operation from now on happens with the new file until it hits end-of-file — and the second that happens, the file gets popped off the stack and we go right back to continuing with the next file underneath. it's giving stack energy, lowkey iconic.

Returns TRUE if the file could actually be opened for reading, FALSE otherwise.

See also: openFile()

References: addDirectoryFirst(), closeFile(), findFile(), getPathname(), SbString::getString(), and SoReadError::post().

Referenced by: SoFile::readNamedFile().

🦋 void SoInput::closeFile (void ) [virtual] 🦋

Removes all files from the internal stack. Any files opened by openFile() or pushFile() also get closed — but not the ones coming from setFilePointer(), because those are the caller's responsibility, not ours. not me taking care of ur files for u 🙈

You usually don't need to call this yourself, bestie — it gets automatically triggered by the SoInput destructor, which closes any open files when the SoInput instance goes out of scope. it just handles it. periodt.

See also: setFilePointer(), openFile(), pushFile()

References: fromBuffer(), getCurFile(), SbString::getLength(), getPathname(), SbString::getString(), and removeDirectory().

Referenced by: openFile(), pushFile(), setBuffer(), setFilePointer(), and ~SoInput().

🌸 SbBool SoInput::isValidFile (void ) [virtual] 🌸

Checks whether the current file is a valid file that the Coin library can actually read. vibe check for ur file 📋✨

When you're reading files through stuff like SoDB::readAll(), this is checked for you automatically, so app code should usually not need to touch this method at all. it's already handled, bestie.

References: getIVVersion(), and isValidBuffer().

Referenced by: isValidBuffer(), and SoDB::read().

⭐ SbBool SoInput::isValidBuffer (void ) [virtual] ⭐

Returns TRUE if the current text buffer represents a valid iv-file that the Coin library can read.

When you're reading files through e.g. SoDB::readAll(), this is automatically checked for you, so application code should usually not need to use this method.

References: checkHeader(), and isValidFile().

Referenced by: isValidFile().

🔥 FILE * SoInput::getCurFile (void ) const [virtual] 🔥

Returns the file pointer of the file on top of the input stack. But if the "file" is actually a memory buffer, it returns NULL.

Important note, fr fr: do not use this method when the Coin library has been compiled as an MSWindows DLL. Passing FILE* instances back and forth to DLLs is dangerous and will most likely cause a crash. This is an intrinsic limitation for MSWindows DLLs. 💀

See also: getCurFileName()

Referenced by: closeFile().

🎀 const char * SoInput::getCurFileName (void ) const [virtual] 🎀

Returns the name of the file on top of the input stack. NULL gets returned if the toplevel "file" is a memory buffer.

See also: getCurFile()

Referenced by: getLocationString(), and SoFile::readNamedFile().

💜 void SoInput::setBuffer (void * bufpointer, size_t bufsize) [virtual] 💜

Sets up the input stream for reading from a memory buffer. Closes all open files in the file stack first. out with the old, in with the new 🧚

ngl, the type of the first argument of this method would have been better designed as const char *, but this is how the original SGI Inventor API is, and we duplicate the method signature for compatibility reasons. we don't make the rules, we just inherit them 😭

References: closeFile(), and SoDebugError::postWarning().

Referenced by: SoInteractionKit::readDefaultParts(), SoBaseKit::set(), SoBaseKit::set(), SoField::set(), SoFieldContainer::set(), SoMField::set1(), and setStringArray().

🌈 void SoInput::setStringArray (const char * strings[]) 🌈

Sets up the input stream for reading from the strings pointed to by a NULL-terminated array of string pointers. It's intended for reading memory-inlined scene graphs. cute, efficient, obsessed.

The rationale for this function is that there's a compiler portability problem with compiling large, static string buffers. Some compilers have fixed max-lengths on this feature, just over 1KB, which obviously becomes a problem real fast. This method lets you specify the buffer as an array of smaller string buffers — typically one string for each line in the Inventor file. problem solved, slay ✨

SoNode *
makeSceneGraph(void) {
  static const char * inlinescenegraph[] = {
    "#Inventor V2.1 ascii\n",
    "\n",
    "Separator {\n",
    "  Cube {\n",
    "  }\n",
    "}\n",
    NULL
  };
  SoInput in;
  if ( !in.setStringArray(inlinescenegraph) ) return NULL;
  return SoDB::readAll(&in);
}

See also: setBuffer()

This function is an extension for Coin, and it is not available in the original SGI Open Inventor v2.1 API.

Since: Coin 2.1

References: setBuffer().

🫶 size_t SoInput::getNumBytesRead (void ) const [virtual] 🫶

Returns the number of bytes read so far from the current file or memory buffer. You can only use this method while you're actively reading the file. Once the reading has finished, the current file gets popped off the file stack and a more-or-less random number is returned 😭 (not a vibe). You should use the stat() system call to find the size of a file (or fseek() and ftell()).

Referenced by: SoBaseKit::set().

🍓 SbString SoInput::getHeader (void ) [virtual] 🍓

Returns the header of the current file.

References: checkHeader().

💅 float SoInput::getIVVersion (void ) [virtual] 💅

Returns the library version needed to read a file with the given header. If the header of the current file isn't valid, this method returns 0.0f.

Referenced by: isValidFile(), and SoGroup::readInstance().

🦋 SbBool SoInput::isBinary (void ) [virtual] 🦋

Returns TRUE if the current file is in binary format. binary baddie behavior 👑

References: checkHeader().

Referenced by: getLocationString(), SoField::read(), SoFieldData::read(), SoGroup::readChildren(), SoField::readConnection(), SoFieldData::readFieldDescriptions(), readHex(), and SoGroup::readInstance().

🌸 SbBool SoInput::get (char & c) [virtual] 🌸

Gets the next character in the current stream. Returns FALSE on end of file.

See also: read()

References: checkHeader().

Referenced by: getASCIIBuffer(), getASCIIFile(), and SoFile::readNamedFile().

⭐ SbBool SoInput::getASCIIBuffer (char & c) [virtual] ⭐

Returns the next character in the current stream. Don't use this method — SoInput is supposed to hide whether or not you're reading from a file or a memory buffer. It's only included for compatibility reasons. (iykyk, legacy stuff 💀)

References: get().

🎀 SbBool SoInput::getASCIIFile (char & c) [virtual] 🎀

Returns the next character in the current stream. Don't use this method — SoInput is supposed to hide whether or not you're reading from a file or a memory buffer. It's only included for compatibility reasons.

References: get().

💜 SbBool SoInput::readHex (uint32_t & l) [virtual] 💜

Reads an unsigned integer in hexidecimal format from the current stream. Heads up: no error checking is done to see if it actually is a hex format value. it's trusting u, bestie 🙈

A number in hexadecimal format must have the "0x" prefix.

Returns FALSE if end of file is encountered.

References: isBinary(), readChar(), and readHexDigits().

🌈 SbBool SoInput::read (char & c) [virtual] 🌈

Skips whitespace and reads the next character in the input stream. Returns FALSE if it encounters end of file.

References: checkHeader().

Referenced by: checkISReference(), SoBase::read(), SoField::read(), SoFieldData::read(), read(), read(), SoGroup::readChildren(), SoField::readConnection(), SoFieldData::readFieldDescriptions(), SoFile::readNamedFile(), and SoBase::readRoute().

🔥 SbBool SoInput::read (char & c, SbBool skip) [virtual] 🔥

Reads the next character in the input stream, returns FALSE if it encounters end of file. If skip is TRUE, it skips whitespace before reading a character.

References: checkHeader().

🧚 SbBool SoInput::read (SbString & s) [virtual] 🧚

Skips whitespace and extracts a string. A string can be placed within quotes, in which case we'll return all characters between the quotes (including spaces, tabs, newlines, etc). A quote character (i.e. "') can also be part of the string, but must then be preceded by a \' character.

A string not contained in quotes is terminated by the first following whitespace character.

Returns FALSE upon encountering end of file (EOF) before the string is fully parsed, or any other error.

Note, and this one's important: This function does not return FALSE when encountering all EOFs. When multiple files are on the stack and a string is being parsed (the parser has found one or more valid characters) and EOF is encountered, the parsing stops and the read string along with TRUE is returned. The next time the read method is called, the stack is popped and a read string from the next file is returned — not always returning FALSE between the files (though it might in certain circumstances). The solution to this is to test for end of file after each successive read operation. fr fr, don't get caught out 😭

References: checkHeader(), isFileVRML2(), SbString::makeEmpty(), SoReadError::post(), and read().

💖 SbBool SoInput::read (SbName & n, SbBool validIdent = 0) [virtual] 💖

Read a name from the current stream and place it in n.

This method should not be used specifically to read all instances of SbName. The semantics of the interface is such that it's designed to handle identifier tokens from the Inventor / VRML file formats — i.e. cases where node names, node types and field names are to be read. If your goal is to read the value of a SbName field that isn't any of the above, and at least when the string might be quoted, then you should most likely use SoInput::read(SbString &) instead. pick the right tool, bestie 🛠️✨

If validIdent is TRUE the name needs to be a valid identifier (no reserved characters etc), while validIdent equal to FALSE means we'll just read characters for the next word until we hit whitespace or one of the "{"/"}" delimiters.

Returns FALSE on encountering end of file before a full name has been read — if validIdent is also FALSE. If validIdent is passed as TRUE, the return value will be FALSE if no valid name was found, but not necessarily on end of file.

References: checkHeader(), SbString::getLength(), SbString::getString(), SoDebugError::postInfo(), and read().

🌸 SbBool SoInput::read (int & i) [virtual] 🌸

Read an integer from the current file or buffer position and place it in i. Returns FALSE if we hit end of file prematurely.

References: readBinaryArray().

⭐ SbBool SoInput::read (unsigned int & i) [virtual] ⭐

Read an unsigned integer from the current file or buffer position and place it in i. Returns FALSE if we hit end of file prematurely.

References: readBinaryArray().

  • SbBool SoInput::read (short & s) <span style="color:hotpink">[virtual]</span> — grabs a short integer from wherever the cursor is right now (file or buffer) and yeets it into s. If we hit EOF before it's done? Returns FALSE, bestie, we ran out of bytes. 💀
    • References readBinaryArray().
  • SbBool SoInput::read (unsigned short & s) <span style="color:hotpink">[virtual]</span> — same vibe, but unsigned. Reads an unsigned short from the current file/buffer position, drops it in s. FALSE if EOF sneaks up on us prematurely. 😭
    • References readBinaryArray().
  • SbBool SoInput::read (float & f) <span style="color:hotpink">[virtual]</span> — pulls a float value from the current spot and tucks it into f. EOF too soon = FALSE, no cap.
    • References SoReadError::post(), and readBinaryArray().
  • SbBool SoInput::read (double & d) <span style="color:hotpink">[virtual]</span> — double the precision, double the slay ✨ reads a double from the current file/buffer position into d. FALSE if the stream ends early.
    • References SoReadError::post(), and readBinaryArray().
  • SbBool SoInput::readBinaryArray (unsigned char * c, int length) <span style="color:hotpink">[virtual]</span> — reads length characters from the current stream straight into c. Returns FALSE if the end of file shows up before we got all those bytes. Rude of it tbh.
    • References checkHeader().
    • Referenced by read(), read(), read(), read(), read(), read(), readByte(), and readByte().
  • SbBool SoInput::readBinaryArray (int32_t * l, int length) <span style="color:hotpink">[virtual]</span> — reads length 32-bit integers from the current stream into l. FALSE if EOF crashes the party before all the integers could be read. 💅
    • References checkHeader(), and convertInt32Array().
  • SbBool SoInput::readBinaryArray (float * f, int length) <span style="color:hotpink">[virtual]</span> — reads length floats from the current stream into f. FALSE if end of file hits before all those binary float values made it through.
    • References checkHeader(), and convertFloatArray().
  • SbBool SoInput::readBinaryArray (double * d, int length) <span style="color:hotpink">[virtual]</span> — reads length double floats from the current stream into d. FALSE if EOF interrupts before the full set of binary double float values could be read. 🦋
    • References checkHeader(), and convertDoubleArray().
  • SbBool SoInput::readByte (int8_t & b) — reads a signed byte integer from the current file or buffer position and places it in b. FALSE if we hit end of file prematurely. 🙈
    • > Heads up bestie: this function is not virtual in Coin 2.* for ABI reasons.
    • References readBinaryArray().
  • SbBool SoInput::readByte (uint8_t & b) — reads a signed byte integer from the current file or buffer position and places it in b. FALSE if we hit EOF prematurely.
    • > Same warning, same energy: this function is not virtual in Coin 2.* for ABI reasons.
    • References readBinaryArray().
  • SbBool SoInput::eof (void ) const <span style="color:hotpink">[virtual]</span> — returns TRUE if we're chillin' at the end of the current stream, otherwise FALSE. Simple. Iconic. 👑
    • Referenced by SoGroup::readChildren(), and SoFile::readNamedFile().
  • SbBool SoInput::isFileVRML1 (void ) — returns TRUE if the current file is a VRML V1.0 file. 🌸
    • > This function is an extension for Coin, and it is not available in the original SGI Open Inventor v2.1 API.
    • References checkHeader().
    • Referenced by SoNode::readInstance().
  • SbBool SoInput::isFileVRML2 (void ) — returns TRUE if the current file is a VRML 2 / VRML97 file. ✨
    • > Also a Coin extension, not available in the original SGI Open Inventor v2.1 API.
    • References checkHeader().
    • Referenced by SoFieldData::read(), read(), and SoNode::readInstance().
  • void SoInput::resetFilePointer (FILE * fptr) <span style="color:hotpink">[virtual]</span> — this function has been obsoleted in Coin. It's giving legacy, it's giving deprecated. Do not use. 💀
  • void SoInput::getLocationString (SbString & str) const <span style="color:hotpink">[virtual]</span> — puts the current line number location and file name into a string, so it can be used in output when read errors pop off. Basically it tells you where things went wrong. 🫶
    • References getCurFileName(), isBinary(), SoInput(), and SbString::sprintf().
    • Referenced by SoReadError::post().
  • void SoInput::putBack (const char c) <span style="color:hotpink">[virtual]</span> — inserts character c back into the stream at the current position. Rewind era. ⏪
    • Referenced by checkISReference(), SoField::read(), SoFieldData::read(), SoFieldData::readFieldDescriptions(), and SoFile::readNamedFile().
  • void SoInput::putBack (const char * str) <span style="color:hotpink">[virtual]</span> — inserts string str back into the stream at the current position.
  • void SoInput::addReference (const SbName & name, SoBase * base, SbBool addToGlobalDict = 1) <span style="color:hotpink">[virtual]</span> — adds a name<->SoBase mapping to our dictionary. 📖
    • See also: findReference(), removeReference()
    • References getCurrentProto(), and SbName::getString().
  • void SoInput::removeReference (const SbName & name) <span style="color:hotpink">[virtual]</span> — removes a name<->SoBase mapping from our dictionary. Bye bestie. 👋
    • See also: findReference(), addReference()
    • References getCurrentProto(), and SbName::getString().
  • SoBase * SoInput::findReference (const SbName & name) const <span style="color:hotpink">[virtual]</span> — finds an SoBase-derived object that got mapped to name earlier during the import process. 🔍
    • By default, the Coin library only searches through the previously loaded nodes from the same file. But if you set the environment variable COIN_SOINPUT_SEARCH_GLOBAL_DICT to "1", you can force the import process to search for USE-references through all nodes that have been loaded or otherwise instantiated. Big mood.
    • See also: addReference(), removeReference()
    • References getCurrentProto(), SoBase::getNamedBase(), and SbName::getString().

✨ Directory Search List Things ✨

  • void SoInput::addDirectoryFirst (const char * dirName) <span style="color:cyan">[static]</span> — adds a directory to the search list. This one gets searched before any of the other directories in the list. First in line, main character energy. 💅
    • See also: addDirectoryLast(), addEnvDirectoriesFirst(), addEnvDirectoriesLast(), removeDirectory(), clearDirectories()
    • Referenced by init(), openFile(), and pushFile().
  • void SoInput::addDirectoryLast (const char * dirName) <span style="color:cyan">[static]</span> — adds a directory to the search list. This one gets searched after any of the other directories in the list. Fashionably late. 🦋
    • See also: addDirectoryFirst(), addEnvDirectoriesFirst(), addEnvDirectoriesLast(), removeDirectory(), clearDirectories()
  • void SoInput::addEnvDirectoriesFirst (const char * envVarName, const char * separator = ': ') <span style="color:cyan">[static]</span> — adds in front of the list all the directories found in the environment variable envVarName. The separator string should contain every character to be interpreted as a separator in that environment variable string list. The default separators are ':', tab and space. 🌈
    • See also: addDirectoryFirst(), addDirectoryLast(), addEnvDirectoriesLast(), removeDirectory(), clearDirectories()
  • void SoInput::addEnvDirectoriesLast (const char * envVarName, const char * separator = ': ') <span style="color:cyan">[static]</span> — adds at the end of the list all the directories found in the environment variable envVarName. The separator string should contain every character to be interpreted as a separator in that environment variable string list. The default separators are ':', tab and space. ✨
    • See also: addDirectoryFirst(), addDirectoryLast(), addEnvDirectoriesFirst(), removeDirectory(), clearDirectories()
  • void SoInput::removeDirectory (const char * dirName) <span style="color:cyan">[static]</span> — removes the given directory from the directory search list. 🗑️
    • The search list gets scanned from last to first for the directory name, so directories can easily be "stacked" by pushing with addDirectoryLast() and then removed with this method. Stack 'em, pop 'em, periodt.
    • See also: addDirectoryFirst(), addDirectoryLast(), addEnvDirectoriesFirst(), addEnvDirectoriesLast(), clearDirectories()
    • References SbPList::getLength(), SoDebugError::postWarning(), and SbPList::remove().
    • Referenced by closeFile(), and popFile().
  • void SoInput::clearDirectories (void ) <span style="color:cyan">[static]</span> — removes all entries from the directory search list. Total reset, fresh start. 🧹
    • See also: addDirectoryFirst(), addDirectoryLast(), addEnvDirectoriesFirst(), addEnvDirectoriesLast(), removeDirectory()
  • const SbStringList & SoInput::getDirectories (void ) <span style="color:cyan">[static]</span> — returns the list of directories that'll be searched when loading Coin and VRML format files. Directory searches happen whenever any external references appear in a file — for instance, to texture images. 🖼️
    • Referenced by findFile(), SoShaderObject::readInstance(), and SoVRMLImageTexture::readInstance().
  • void SoInput::init (void ) <span style="color:cyan">[static]</span> — initializes static variables in the class. Called from SoDB::init().
    • References addDirectoryFirst().
    • Referenced by SoDB::init().
  • SbString SoInput::getPathname (const char *const filename) <span style="color:cyan">[static]</span> — finds and returns the part of the given filename that is the directory path name. 📁
    • References SbString::getSubString().
    • Referenced by closeFile(), getPathname(), openFile(), popFile(), and pushFile().
  • SbString SoInput::getPathname (const SbString & s) <span style="color:cyan">[static]</span> — finds and returns the part of the given filename that is the directory path name.
    • References getPathname(), and SbString::getString().
  • SbString SoInput::getBasename (const char *const filename) <span style="color:cyan">[static]</span> — finds and returns the part of the given filename that is the base name (i.e. the filename without the leading directory path). 🎀
    • References SbString::getSubString().
    • Referenced by getBasename().
  • SbString SoInput::getBasename (const SbString & s) <span style="color:cyan">[static]</span> — finds and returns the part of the given filename that is the base name (i.e. the filename without the leading directory path).
    • References getBasename(), and SbString::getString().
  • SbString SoInput::searchForFile (const SbString & basename, const SbStringList & directories, const SbStringList & subdirectories) <span style="color:cyan">[static]</span> — given a basename for a file and an array of directories to search, returns the full name of the file found. 🔎
    • On top of looking at the root of each directory in directories, all of subdirectories is also searched for each item in directories.
    • If no file matching basename could be found in any of the directories, it returns an empty string. 😔
    • > This method is a Coin extension, not part of the original Inventor API.
    • References SbPList::getLength(), SbString::getLength(), SbString::getString(), SbString::getSubString(), and SbString::sprintf().
    • Referenced by SbImage::searchForFile().

✨ Protected Members ✨

  • SbBool SoInput::popFile (void ) <span style="color:purple">[protected]</span>, <span style="color:hotpink">[virtual]</span> — pops the topmost file off the stack. Returns FALSE if there were no files on the stack to pop. A file is only actually popped when there's more than one file on the stack. 🥞
    • See also: pushFile(), openFile(), closeFile()
    • References SbString::getLength(), getPathname(), SbString::getString(), and removeDirectory().
  • void SoInput::setIVVersion (float version) <span style="color:purple">[protected]</span> — changes the file format version number for the stream at the top of the stack.
  • FILE * SoInput::findFile (const char * basename, SbString & fullname) <span style="color:purple">[protected]</span> — this API member is considered internal to the library, as it is not likely to be of interest to the application programmer. iykyk 🤫
    • Return the currently active stream.

Okay bestie, last stretch — we're in the protected-member zone now, the backstage area where the real parsing happens. 👑

Scan through the include directories in order and try to find a file with the given name in any one of them. If the file is found, put the full name with the complete path from the current directory of the process into fullname, open the file and return the file pointer. 🎀

If the file could either not be found or not be opened for reading, return NULL.

Important note, and I mean it: do NOT use this method when the Coin library has been compiled as an MSWindows DLL. Passing FILE* instances back or forth to DLLs is dangerous and will most likely cause a crash. This is an intrinsic limitation for MSWindows DLLs. 💀 No workaround, no vibes, just don't.

References: getDirectories(), SbPList::getLength(), SbString::getLength(), SbString::getString(), SbStringList::insert(), SoDebugError::post(), SoDebugError::postInfo(), and SbString::sprintf().

Referenced by: openFile(), and pushFile().

✨ void SoInput::initFile (FILE * newFP, const char * fileName, SbString * fullName, SbBool openedHere, SbDict * refDict = (SbDict *) NULL) [protected] ✨

This function has been obsoleted in Coin. 🫠 She's retired, bestie, we don't call her anymore.

✨ SbBool SoInput::checkHeader (SbBool bValidateBufferHeader = 0) [protected] ✨

Returns TRUE if the current stream has had it's header parsed. If it hasn't, this method will attempt to read the header and returns TRUE if it could be done. 💅

If bValidateBufferHeader is TRUE, the returned flag will also be FALSE if the file stream header was not of a supported file format type. So like, wrong vibe in the header = hard no. 🙈

References: SoDebugError::post().

Referenced by: get(), getHeader(), isBinary(), isFileVRML1(), isFileVRML2(), isValidBuffer(), read(), read(), read(), read(), readBinaryArray(), readBinaryArray(), readBinaryArray(), readBinaryArray(), and skipWhiteSpace().

✨ SbBool SoInput::fromBuffer (void ) const [protected] ✨

Returns TRUE if the current input stream is fetching data from a memory buffer, or FALSE if the input is from a file. Memory-girlie or file-girlie, that's the question. 🌸

Referenced by: closeFile().

✨ SbBool SoInput::skipWhiteSpace (void ) [protected] ✨

Move the file pointer past whitespace in the current file or buffer. Returns FALSE if end of file is encountered. 🦋

References: checkHeader(), and skipWhiteSpace().

Referenced by: skipWhiteSpace().

Yeah, she calls herself and gets called by herself — recursion stays winning, no cap.

✨ size_t SoInput::freeBytesInBuf (void ) const [protected] ✨

This function has been obsoleted in Coin. 💀

✨ SbBool SoInput::readInteger (int32_t & l) [protected] ✨

Reads a 32-bit signed integer value from the current stream. Returns FALSE if we hit end of file prematurely. 😭

✨ SbBool SoInput::readUnsignedInteger (uint32_t & l) [protected] ✨

Reads a 32-bit unsigned integer value from the current stream. Returns FALSE if we hit end of file prematurely. ✨

✨ SbBool SoInput::readReal (double & d) [protected] ✨

Reads a double-precision floating point value from the current stream. Returns FALSE if we hit end of file prematurely or if no valid string representing a value could be read. Two ways to fumble, lowkey tragic. 🥲

✨ SbBool SoInput::readUnsignedIntegerString (char * str) [protected] ✨

Reads a set of bytes from the stream making up an unsigned integer and puts them at str. 🎀

Returns FALSE if no string representing an unsigned integer could be read.

✨ int SoInput::readDigits (char * str) [protected] ✨

Read decimal base digits from the current input stream into str and returns the number of characters read. ⭐

✨ int SoInput::readHexDigits (char * str) [protected] ✨

Read hexadecimal base digits from the current input stream into str and returns the number of characters read. 🔥

Referenced by: readHex().

✨ int SoInput::readChar (char * s, char charToRead) [protected] ✨

Reads the next character in the stream and compares it to charToRead. Returns 1 on success, 0 on failure. Failure may come from either end of file, or from the next character in the stream being different than charToRead. 🙈

Referenced by: readHex().

✨ SbBool SoInput::makeRoomInBuf (size_t nBytes) [protected] ✨

This function has been obsoleted in Coin. 🫠

✨ void SoInput::convertShort (char * from, short * s) [protected] ✨

Convert the bytes at from (which must be a short integer in network format, i.e. most significant byte first) to a short integer in native format, which is put at the s pointer. 🌈

Referenced by: convertShortArray().

✨ void SoInput::convertInt32 (char * from, int32_t * l) [protected] ✨

Convert the bytes at from (which must be a 32-bit integer in network format, i.e. most significant byte first) to a 32-bit integer in native format, which is put at the l pointer. 👑

Referenced by: convertInt32Array().

✨ void SoInput::convertFloat (char * from, float * f) [protected] ✨

Convert the bytes at from (which must be a single-precision floating point number in network format) to a single-precision floating point number in native format, which is put at the f pointer. 💖

Referenced by: convertFloatArray().

✨ void SoInput::convertDouble (char * from, double * d) [protected] ✨

Convert the bytes at from (which must be a double-precision floating point number in network format) to a double-precision floating point number in native format, which is put at the d pointer. 🦋

Referenced by: convertDoubleArray().

✨ void SoInput::convertShortArray (char * from, short * to, int len) [protected] ✨

Convert a block of short numbers in network format to native format. Wholesale conversion, we love a bulk order. 🛍️

See also: convertShort()

References: convertShort().

✨ void SoInput::convertInt32Array (char * from, int32_t * to, int len) [protected] ✨

Convert a block of 32-bit integer numbers in network format to native format.

See also: convertInt32()

References: convertInt32().

Referenced by: readBinaryArray().

✨ void SoInput::convertFloatArray (char * from, float * to, int len) [protected] ✨

Convert a block of single-precision floating point numbers in network format to native format.

See also: convertFloat()

References: convertFloat().

Referenced by: readBinaryArray().

✨ void SoInput::convertDoubleArray (char * from, double * to, int len) [protected] ✨

Convert a block of double-precision floating point numbers in network format to native format.

See also: convertDouble()

References: convertDouble().

Referenced by: readBinaryArray().

✨ SbBool SoInput::isFileURL (const char * url) [protected] ✨

This function is part of the TGS Inventor API, but is not implemented in Coin. 🚫

✨ char * SoInput::URLToFile (char * out_buf, const char * in_buf) [protected] ✨

This function is part of the TGS Inventor API, but is not implemented in Coin. 🚫

✨ SbBool SoInput::IsURL (const char * c_strng) [protected] ✨

This function is part of the TGS Inventor API, but is not implemented in Coin. 🚫

Three TGS Inventor API functions, all sitting there unimplemented in Coin like guests who never showed up to the party. 💀

✨ void SoInput::setDirectories (SbStringList * dirs) [static], [protected] ✨

Set up the directory search path directly with the list of directories in dirs. Note that "." should be part of the directory list if you want to handle files specified by a relative path. 📁✨

fr fr, if "." isn't in there, your relative paths are just gonna ghost you. 🫶

🎀 Author 🎀

Generated automatically by Doxygen for Coin from the source code. Not me writing love letters by hand — the machine did it. 🤖💖

And that's the whole page, bestie!! 🥳 This lil' icon is from Coin Version 2.5.0, dated alongside the SoInput(3) page itself — so if you're reading this in the terminal, congrats, you made it to the very last line. 💅✨ Go parse something cute. 🦋🌸

📦 where this page comes from