Provided by: libcoin60-doc_3.1.3-2_all bug

NAME

       SoOutput -

       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.

SYNOPSIS

       #include <Inventor/SoOutput.h>

   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 mutiple passes).
       See also:
           setStage(), getStage()

   enum SoOutput::Annotations Values from this enum is used for debugging purposes to annotate
       the output from a write operation.

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

       See also:
           openFile(), setBuffer(), getFilePointer()

   FILE * SoOutput::getFilePointer (void) const [virtual] Returns the current filepointer. 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 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.

       See also:
           setFilePointer()

   SbBool SoOutput::openFile (const char *constfileName) [virtual] Opens a file for writing. If
       the file can not be opened or is not writeable, FALSE will be returned.
       Files opened by this method will automatically be closed if the user supplies another
       filepointer, 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 floatlevel = 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's 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_tinitSize, SoOutputReallocCB *reallocFunc,
       int32_toffset = 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, stand-alone usage example which shows how to write a scene graph to a
       memory buffer:

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

         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, '%s0, 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 SbBoolflag) [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 intprecision) [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 (Stagestage) 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 intlevels = 1) Increase indentation level in the file.
       See also:
           decrementIndent(), indent()

   void SoOutput::decrementIndent (const intlevels = 1) Decrease indentation level in the file.
       See also:
           incrementIndent(), indent()

   void SoOutput::write (const charc) [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 inti) [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 inti) [virtual] Write i as a character string, or as an
       architecture independent binary pattern if the setBinary() flag is activated.
   void SoOutput::write (const shorts) [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 shorts) [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 floatf) [virtual] Write f as a character string.
   void SoOutput::write (const doubled) [virtual] Write d as a character string.
   void SoOutput::writeBinaryArray (const unsigned char *constc, const intlength) [virtual] Write
       the given number of bytes to either a file or a memory buffer in binary format.
   void SoOutput::writeBinaryArray (const int32_t *constl, const intlength) [virtual] Write an
       length array of int32_t values in binary format.
   void SoOutput::writeBinaryArray (const float *constf, const intlength) [virtual] Write an
       array of float values in binary format.
   void SoOutput::writeBinaryArray (const double *constd, const intlength) [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
       filepointer or buffer.
   void SoOutput::setCompact (SbBoolflag) 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 tries 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_tbits) Set up annotation of different aspects of the
       output data. This is not useful for much else than debugging purposes, I s'pose.
   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, intrefid) Sets the reference for base
       manually.
   void SoOutput::addDEFNode (SbNamename) Adds name to the set of currently DEF'ed node names so
       far in the output process.
   SbBool SoOutput::lookupDEFNode (SbNamename) Checks whether name is already DEF'ed at this
       point in the output process. Returns TRUE if name is DEF'ed.
   void SoOutput::removeDEFNode (SbNamename) 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 of 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_tbytes) [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
       realloction callback function argument of setBuffer() was not NULL.

   void SoOutput::convertShort (shorts, 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_tl, 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 (floatf, 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 (doubled, 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, intlen) [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, intlen) [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, intlen) [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, intlen) [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.