--- name: "SoOutput" section: "3" platform: "linux" package: "coin" version: "1:4.0.10-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/SoOutput" --- # SoOutput(3) The SoOutput class is an abstraction of an output stream. ## NAME SoOutput - The **SoOutput** class is an abstraction of an output stream. ## SYNOPSIS \#include \ ### Public Types enum **Stage** { **COUNT\_REFS**, **WRITE** }\ enum **Annotations** { **ADDRESSES** = 0x01, **REF\_COUNTS** = 0x02 }\ ### Public Member Functions **SoOutput** (void)\ **SoOutput** (**SoOutput** \*dictOut)\ virtual **~SoOutput** ()\ virtual void **setFilePointer** (FILE \*newFP)\ virtual FILE \* **getFilePointer** (void) const\ virtual SbBool **openFile** (const char \*const fileName)\ virtual void **closeFile** (void)\ SbBool **setCompression** (const **SbName** &compmethod, const float level=0.5f)\ virtual void **setBuffer** (void \*bufPointer, size\_t initSize, SoOutputReallocCB \*reallocFunc, int32\_t offset=0)\ virtual SbBool **getBuffer** (void \*&bufPointer, size\_t &nBytes) const\ virtual size\_t **getBufferSize** (void) const\ virtual void **resetBuffer** (void)\ virtual void **setBinary** (const SbBool flag)\ virtual SbBool **isBinary** (void) const\ virtual void **setHeaderString** (const **SbString** &str)\ virtual void **resetHeaderString** (void)\ virtual void **setFloatPrecision** (const int precision)\ void **setStage** (**Stage** stage)\ **Stage** **getStage** (void) const\ void **incrementIndent** (const int levels=1)\ void **decrementIndent** (const int levels=1)\ virtual void **write** (const char c)\ virtual void **write** (const char \*s)\ virtual void **write** (const **SbString** &s)\ virtual void **write** (const **SbName** &n)\ virtual void **write** (const int i)\ virtual void **write** (const unsigned int i)\ virtual void **write** (const short s)\ virtual void **write** (const unsigned short s)\ virtual void **write** (const float f)\ virtual void **write** (const double d)\ virtual void **writeBinaryArray** (const unsigned char \*c, const int length)\ virtual void **writeBinaryArray** (const int32\_t \*const l, const int length)\ virtual void **writeBinaryArray** (const float \*const f, const int length)\ virtual void **writeBinaryArray** (const double \*const d, const int length)\ virtual void **indent** (void)\ virtual void **reset** (void)\ void **setCompact** (SbBool flag)\ SbBool **isCompact** (void) const\ void **setAnnotation** (uint32\_t bits)\ uint32\_t **getAnnotation** (void)\ int **addReference** (const **SoBase** \*base)\ int **findReference** (const **SoBase** \*base) const\ void **setReference** (const **SoBase** \*base, int refid)\ void **addDEFNode** (**SbName** name)\ SbBool **lookupDEFNode** (**SbName** name)\ void **removeDEFNode** (**SbName** name)\ void **pushProto** (**SoProto** \*proto)\ **SoProto** \* **getCurrentProto** (void) const\ void **popProto** (void)\ void **addRoute** (**SoFieldContainer** \*from, const **SbName** &fromfield, **SoFieldContainer** \*to, const **SbName** &tofield)\ void **resolveRoutes** (void)\ ### Static Public Member Functions static const **SbName** \* **getAvailableCompressionMethods** (unsigned int &num)\ static **SbString** **getDefaultASCIIHeader** (void)\ static **SbString** **getDefaultBinaryHeader** (void)\ ### Protected Member Functions SbBool **isToBuffer** (void) const\ size\_t **bytesInBuf** (void) const\ SbBool **makeRoomInBuf** (size\_t nBytes)\ void **convertShort** (short s, char \*to)\ void **convertInt32** (int32\_t l, char \*to)\ void **convertFloat** (float f, char \*to)\ void **convertDouble** (double d, char \*to)\ void **convertShortArray** (short \*from, char \*to, int len)\ void **convertInt32Array** (int32\_t \*from, char \*to, int len)\ void **convertFloatArray** (float \*from, char \*to, int len)\ void **convertDoubleArray** (double \*from, char \*to, int len)\ ### Static Protected Member Functions static **SbString** **padHeader** (const **SbString** &inString)\ ### Protected Attributes SbBool **wroteHeader**\ ## Detailed Description The **SoOutput** class is an abstraction of an output stream. **SoOutput** offers the ability to write basic types to a file or a memory buffer in either ASCII or binary format. **See also** **SoInput**, **SoWriteAction** ## Member Enumeration Documentation ### enum SoOutput::Stage Enumerates the possible stages of a write operation (writing needs to be done in multiple passes). **See also** **setStage()**, **getStage()** **Enumerator** - ***COUNT\_REFS*** Not writing, just counting the internal references in the scene graph. - ***WRITE*** Signifies that actual data export should take place during this pass. ### enum SoOutput::Annotations Values from this enum is used for debugging purposes to annotate the output from a write operation. **Enumerator** - ***ADDRESSES*** Annotate output with pointer address information. - ***REF\_COUNTS*** Annotate output with reference counts of the objects written. ## Constructor & Destructor Documentation ### SoOutput::SoOutput (void ) The default constructor makes an **SoOutput** instance which will write to the standard output. **See also** **setFilePointer()**, **openFile()**, **setBuffer()** ### SoOutput::SoOutput (SoOutput \* dictOut) Constructs an **SoOutput** which has a copy of the set of named references from *dictOut*. ### SoOutput::~SoOutput (void ) \[virtual\] Destructor. ## Member Function Documentation ### void SoOutput::setFilePointer (FILE \* newFP) \[virtual\] Set up a new file pointer which we will write to. Important note: do *not* use this method when the Coin library has been compiled as a Microsoft Windows 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 Microsoft Windows DLLs. **See also** **openFile()**, **setBuffer()**, **getFilePointer()** ### FILE \* SoOutput::getFilePointer (void ) const \[virtual\] Returns the current file pointer. If we're writing to a memory buffer, NULL is returned. Important note: do *not* use this method when the Coin library has been compiled as a Microsoft Windows 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 Microsoft Windows DLLs. **See also** **setFilePointer()** ### SbBool SoOutput::openFile (const char \*const fileName) \[virtual\] Opens a file for writing. If the file cannot be opened or is not writable, *FALSE* will be returned. Files opened by this method will automatically be closed if the user supplies another file pointer, another filename for writing, or if the **SoOutput** instance is deleted. **See also** **setFilePointer()**, **setBuffer()**, **closeFile()** ### void SoOutput::closeFile (void ) \[virtual\] Closes the currently opened file, but only if the file was passed to **SoOutput** through the **openFile()** method. **See also** **openFile()** ### SbBool SoOutput::setCompression (const SbName & compmethod, const float level = 0.5f) Sets the compression method and level used when writing the file. *compmethod* is the compression library/method to use when compressing. *level* is the compression level, where 0.0 means no compression and 1.0 means maximum compression. Currently *BZIP2*, *GZIP* are the only compression methods supported, and you have to compile Coin with zlib and bzip2-support to enable them. Supply *compmethod* = *NONE* or *level* = 0.0 if you want to disable compression. The compression is disabled by default. Please note that it's not possible to compress when writing to a memory buffer. This method will return *TRUE* if the compression method selected is available. If it is not available, *FALSE* will be returned and compression is disabled. **See also** **getAvailableCompressionMethods()** **Since** Coin 2.1 ### const SbName \* SoOutput::getAvailableCompressionMethods (unsigned int & num) \[static\] Returns the array of available compression methods. The number of elements in the array will be stored in *num*. **See also** **setCompression()** **Since** Coin 2.1 ### void SoOutput::setBuffer (void \* bufPointer, size\_t initSize, SoOutputReallocCB \* reallocFunc, int32\_t offset = 0) \[virtual\] Sets up a memory buffer of size *initSize* for writing. Writing will start at *bufPointer* + *offset*. If the buffer is filled up, *reallocFunc* is called to get more memory. If *reallocFunc* returns *NULL*, further writing is disabled. Important note: remember that the resultant memory buffer after write operations have completed may reside somewhere else in memory than on *bufPointer* if *reallocFunc* is set. It is a good idea to make it a habit to always use **getBuffer()** to retrieve the memory buffer pointer after write operations. Here's a complete, standalone usage example which shows how to write a scene graph to a memory buffer: ``` #include #include #include #include static char * buffer; static size_t buffer_size = 0; static void * buffer_realloc(void * bufptr, size_t size) { buffer = (char *)realloc(bufptr, size); buffer_size = size; return buffer; } static SbString buffer_writeaction(SoNode * root) { SoOutput out; buffer = (char *)malloc(1024); buffer_size = 1024; out.setBuffer(buffer, buffer_size, buffer_realloc); SoWriteAction wa(&out); wa.apply(root); SbString s(buffer); free(buffer); return s; } int main(int argc, char ** argv) { SoDB::init(); SoSeparator * root = new SoSeparator; root->ref(); root->addChild(new SoCone); SbString s = buffer_writeaction(root); (void)fprintf(stdout, "%s\n", s.getString()); root->unref(); return 0; } ``` **See also** **getBuffer()**, **getBufferSize()**, **resetBuffer()** ### SbBool SoOutput::getBuffer (void \*& bufPointer, size\_t & nBytes) const \[virtual\] Returns the current buffer in *bufPointer* and the current write position of the buffer in *nBytes*. If we're writing into a file and not a memory buffer, *FALSE* is returned and the other return values will be undefined. **See also** **getBufferSize()** ### size\_t SoOutput::getBufferSize (void ) const \[virtual\] Returns total size of memory buffer. **See also** **getBuffer()** ### void SoOutput::resetBuffer (void ) \[virtual\] Reset the memory buffer write pointer back to the beginning of the buffer. ### void SoOutput::setBinary (const SbBool flag) \[virtual\] Set whether or not to write the output as a binary stream. **See also** **isBinary()** ### SbBool SoOutput::isBinary (void ) const \[virtual\] Returns a flag which indicates whether or not we're writing the output as a binary stream. **See also** **setBinary()** ### void SoOutput::setHeaderString (const SbString & str) \[virtual\] Set the output file header string. **See also** **resetHeaderString()**, **getDefaultASCIIHeader()**, **getDefaultBinaryHeader()** ### void SoOutput::resetHeaderString (void ) \[virtual\] Reset the header string to the default one. **See also** **setHeaderString()**, **getDefaultASCIIHeader()**, **getDefaultBinaryHeader()** ### void SoOutput::setFloatPrecision (const int precision) \[virtual\] Set the precision used when writing floating point numbers to ASCII files. *precision* should be between 0 and 8. The double precision will be set to *precision* \* 2. ### void SoOutput::setStage (Stage stage) Sets an indicator on the current stage. This is necessary to do as writing has to be done in multiple stages to account for the export of references/connections within the scene graphs. This method is basically just used from within **SoWriteAction**, and should usually not be of interest to the application programmer. Do not use it unless you *really* know what you are doing. **See also** **getStage()** ### SoOutput::Stage SoOutput::getStage (void ) const Returns an indicator on the current write stage. Writing is done in two passes, one to count and check connections, one to do the actual ASCII or binary export of data. You should not need to use this method, as it is meant for internal purposes in Coin. **See also** **setStage()** ### void SoOutput::incrementIndent (const int levels = 1) Increase indentation level in the file. **See also** **decrementIndent()**, **indent()** ### void SoOutput::decrementIndent (const int levels = 1) Decrease indentation level in the file. **See also** **incrementIndent()**, **indent()** ### void SoOutput::write (const char c) \[virtual\] Write the character in *c*. For binary write, the character plus 3 padding zero characters will be written. ### void SoOutput::write (const char \* s) \[virtual\] Write the character string pointed to by *s*. For binary write, a 4-byte MSB-ordered integer with the string length, plus the string plus padding zero characters to get on a 4-byte boundary (if necessary) will be written. ### void SoOutput::write (const SbString & s) \[virtual\] Write the character string in *s*. The string will be written with apostrophes. Cast **SbString** to char \* to write without apostrophes. If we are supposed to write in binary format, no apostrophes will be added, and writing will be done in the exact same manner as with **SoOutput::write(const char \* s)**. ### void SoOutput::write (const SbName & n) \[virtual\] Write the character string in *n*. The name will be enclosed by apostrophes. If you want to write an **SbName** instance without the apostrophes, cast the argument to a char \*. If we are supposed to write in binary format, no apostrophes will be added, and writing will be done in the exact same manner as with **SoOutput::write(const char \* s)**. ### void SoOutput::write (const int i) \[virtual\] Write *i* as a character string, or as an architecture independent binary pattern if the **setBinary()** flag is activated. ### void SoOutput::write (const unsigned int i) \[virtual\] Write *i* as a character string, or as an architecture independent binary pattern if the **setBinary()** flag is activated. ### void SoOutput::write (const short s) \[virtual\] Write *s* as a character string, or as an architecture independent binary pattern if the **setBinary()** flag is activated. ### void SoOutput::write (const unsigned short s) \[virtual\] Write *s* as a character string, or as an architecture independent binary pattern if the **setBinary()** flag is activated. If we're writing in ASCII format, the value will be written in base 16 (hexadecimal). ### void SoOutput::write (const float f) \[virtual\] Write *f* as a character string. ### void SoOutput::write (const double d) \[virtual\] Write *d* as a character string. ### void SoOutput::writeBinaryArray (const unsigned char \* constc, const int length) \[virtual\] Write the given number of bytes to either a file or a memory buffer in binary format. ### void SoOutput::writeBinaryArray (const int32\_t \*const l, const int length) \[virtual\] Write an *length* array of int32\_t values in binary format. ### void SoOutput::writeBinaryArray (const float \*const f, const int length) \[virtual\] Write an array of float values in binary format. ### void SoOutput::writeBinaryArray (const double \*const d, const int length) \[virtual\] Write an array of double values in binary format. ### void SoOutput::indent (void ) \[virtual\] Call this method after writing a newline to a file to indent the next line to the correct position. **See also** **incrementIndent()**, **decrementIndent()** ### void SoOutput::reset (void ) \[virtual\] Reset all value and make ready for using another file pointer or buffer. ### void SoOutput::setCompact (SbBool flag) Set up the output to be more compact than with the default write routines. ### SbBool SoOutput::isCompact (void ) const Returns whether or not the write routines try to compact the data when writing it (i.e. using less whitespace, etc). Note that "compact" in this sense does *not* mean "bitwise compression", as it could easily be mistaken for. ### void SoOutput::setAnnotation (uint32\_t bits) Set up annotation of different aspects of the output data. This is not useful for much else than debugging purposes, I suppose. ### uint32\_t SoOutput::getAnnotation (void ) Returns the current annotation debug bitflag settings. ### SbString SoOutput::getDefaultASCIIHeader (void ) \[static\] Return the default header string written to ASCII files. **See also** **setHeaderString()**, **resetHeaderString()**, **getDefaultBinaryHeader()** ### SbString SoOutput::getDefaultBinaryHeader (void ) \[static\] Return the default header string written to binary files. **See also** **setHeaderString()**, **resetHeaderString()**, **getDefaultASCIIHeader()** ### int SoOutput::addReference (const SoBase \* base) Makes a unique id for *base* and adds a mapping into our dictionary. ### int SoOutput::findReference (const SoBase \* base) const Returns the unique identifier for *base* or -1 if not found. ### void SoOutput::setReference (const SoBase \* base, int refid) Sets the reference for *base* manually. ### void SoOutput::addDEFNode (SbName name) Adds *name* to the set of currently DEF'ed node names so far in the output process. ### SbBool SoOutput::lookupDEFNode (SbName name) Checks whether *name* is already DEF'ed at this point in the output process. Returns TRUE if *name* is DEF'ed. ### void SoOutput::removeDEFNode (SbName name) Removes *name* from the set of DEF'ed node names. Used after the last reference to a DEF'ed node if we want to reuse the DEF at a later point in the file. ### void SoOutput::pushProto (SoProto \* proto) *This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.*\ 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 ### SoProto \* SoOutput::getCurrentProto (void ) const *This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.*\ 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 ### void SoOutput::popProto (void ) *This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.*\ 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 ### void SoOutput::addRoute (SoFieldContainer \* from, const SbName & fromfield, SoFieldContainer \* to, const SbName & tofield) *This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.*\ 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 ### void SoOutput::resolveRoutes (void ) *This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.*\ 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 ### SbBool SoOutput::isToBuffer (void ) const \[protected\] Returns *TRUE* if we're set up to write to a memory buffer. ### size\_t SoOutput::bytesInBuf (void ) const \[protected\] Returns current write position. Note that for memory buffer writing, this includes the offset from **SoOutput::setBuffer()**, if any. ### SbBool SoOutput::makeRoomInBuf (size\_t bytes) \[protected\] Check that the current memory buffer has enough space to contain the given number of bytes needed for the next write operation. Returns *FALSE* if there's not enough space left, otherwise *TRUE*. Note that there will automatically be made an attempt at allocating more memory if the reallocation callback function argument of **setBuffer()** was not *NULL*. ### void SoOutput::convertShort (short s, char \* to) \[protected\] Convert the short integer in *s* to most-significant-byte first format and put the resulting bytes sequentially at *to*. **See also** **SoInput::convertShort()** ### void SoOutput::convertInt32 (int32\_t l, char \* to) \[protected\] Convert the 32-bit integer in *l* to most-significant-byte first format and put the resulting bytes sequentially at *to*. **See also** **SoInput::convertInt32()** ### void SoOutput::convertFloat (float f, char \* to) \[protected\] Convert the single-precision floating point number in *f* to most-significant-byte first format and put the resulting bytes sequentially at *to*. **See also** **SoInput::convertFloat()** ### void SoOutput::convertDouble (double d, char \* to) \[protected\] Convert the double-precision floating point number in *d* to most-significant-byte first format and put the resulting bytes sequentially at *to*. **See also** **SoInput::convertDouble()** ### void SoOutput::convertShortArray (short \* from, char \* to, int len) \[protected\] Convert *len* short integer values from the array at *from* into the array at *to* from native host format to network independent format (i.e. most significant byte first). ### void SoOutput::convertInt32Array (int32\_t \* from, char \* to, int len) \[protected\] Convert *len* 32-bit integer values from the array at *from* into the array at *to* from native host format to network independent format (i.e. most significant byte first). ### void SoOutput::convertFloatArray (float \* from, char \* to, int len) \[protected\] Convert *len* single-precision floating point values from the array at *from* into the array at *to* from native host format to network independent format (i.e. most significant byte first). ### void SoOutput::convertDoubleArray (double \* from, char \* to, int len) \[protected\] Convert *len* double-precision floating point values from the array at *from* into the array at *to* from native host format to network independent format (i.e. most significant byte first). ### SbString SoOutput::padHeader (const SbString & inString) \[static\], \[protected\] Pads the header we're writing so it contains the correct amount of bytes for the alignment of the following binary writes. ## Member Data Documentation ### SbBool SoOutput::wroteHeader \[protected\] Indicates whether or not the file format header has been written out. As long as this is *FALSE*, the header will be written once upon the first invocation of any write method in the class. ## Author Generated automatically by Doxygen for Coin from the source code.