SoInput(3)

📦 version 3.1.3, in fedora 43, fedora 44

👑 SoInput — the `SoInput(3)` page, Library Functions Manual edition

okay bestie, sit down, hydrate, because this is THE file-reading glow-up of the century 💖

💖 NAME

SoInput — the class that's basically the abstract vibe of "importing files" in Coin. It's the abstraction layer over file import functionality. Periodt.

✨ 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=FALSE)
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=FALSE)
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 readByte (int8_t &b)
virtual SbBool readByte (uint8_t &b)
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)
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=TRUE)
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=NULL)
SbBool checkHeader (SbBool bValidateBufferHeader=FALSE)
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)

🌈 Detailed Description

SoInput is the abstraction of file import functionality. Like, that IS the job description.

This class handles most of the chores of doing data import in Coin. It slaps a whole layer of abstraction over the read operations so the rest of the Coin code literally cannot tell whether it's reading from a file, from a memory buffer, or from stdin. Iconic behavior honestly 🫶

SoInput also handles checking file validity, plus it keeps track of information about features in the various file formats that are supported.

Example usage, bestie, look how clean:

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, and I need you to actually hear me: there are several public and protected methods which make 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, because 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. Not a skill issue, just a Windows DLL thing 💀

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.

🎀 Constructor & Destructor Documentation

SoInput::SoInput (void )

Constructor. If no filepointer is set, input will be read from stdin. yes girl, it'll just vibe with stdin ✨

SoInput::SoInput (SoInput * dictIn)

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

SoInput::~SoInput (void ) [virtual]

Destructor. Runs SoInput::closeFile() to close any open files. She cleans up after herself, as she should 💅

💜 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.