SoOutput(3IV)

NAME
     SoOutput (SoOut) - used to write Inventor data files

INHERITS FROM
     SoOutput

SYNOPSIS
     #include <Inventor_c/SoOutput.h>

     typedef void *      SoOutputReallocCB(void *ptr, size_t newSize)
     typedef SoOutput    SoOut

          Functions from class SoOutput:

     SoOutput *          SoOutCreate()
     void                SoOutDelete(SoOut *this)
     void                SoOutSetFilePtr(SoOut *this, FILE *newFP)
     FILE *              SoOutGetFilePtr(const SoOut *this)
     SbBool              SoOutOpenFile(SoOut *this, const char *fileName)
                         SoOutCloseFile(SoOut *this)
     void                SoOutSetBuf(SoOut *this, void *bufPointer, size_t
                              initSize, SoOutputReallocCB *reallocFunc,
                              int32_t offset = 0)
     SbBool              SoOutGetBuf(const SoOut *this, void **bufPointer,
                              size_t *nBytes)
     size_t              SoOutGetBufferSize(const SoOut *this)
     void                SoOutResetBuffer(SoOut *this)
     void                SoOutSetBin(SoOut *this, SbBool flag)
     SbBool              SoOutIsBin(const SoOut *this)
     void                SoOutSetHdrStr(SoOut *this, const SbString *str)
     void                SoOutResetHdrStr(SoOut *this)
     SbString            SoOutGetDfltASCIIHdr()
     SbString            SoOutGetDfltBinHdr()
     void                SoOutSetFltPrcsn(SoOut *this, int precision)


DESCRIPTION
     This class is used for writing Inventor data files. It supports both
     ASCII (default) and binary formats and provides some convenience
     functions for handling files. It can also write to a buffer in memory as
     well as to a file pointer. A user-defined header can be specified for the
     output file. An instance of SoOutput is contained in an SoWriteAction;
     this is typically the only instance needed.

FUNCTIONS
     SoOutput *          SoOutCreate()
     void                SoOutDelete(SoOut *this)
          Constructor and destructor. The default SoOutput writes to stdout.
          The destructor closes any files opened by the SoOutput.

     void                SoOutSetFilePtr(SoOut *this, FILE *newFP)
          Sets file pointer to write to.
     FILE *              SoOutGetFilePtr(const SoOut *this)
          Returns the file pointer in use, or NULL if using a buffer.

     SbBool              SoOutOpenFile(SoOut *this, const char *fileName)
          Opens named file, sets file pointer to result. This returns FALSE on
          error.

                         SoOutCloseFile(SoOut *this)
          Closes current file if opened with  SoOutOpenFile().

     void                SoOutSetBuf(SoOut *this, void *bufPointer, size_t
                              initSize, SoOutputReallocCB *reallocFunc,
                              int32_t offset = 0)
          Sets up memory buffer to write to, initial size, reallocation
          function (which is called if there is not enough room in the
          buffer), and offset in the buffer at which to begin writing. If the
          reallocation function returns NULL, writing will be disabled.

     SbBool              SoOutGetBuf(const SoOut *this, void **bufPointer,
                              size_t *nBytes)
          Returns pointer to memory buffer being written to and the new size
          of the buffer. Returns FALSE if not writing into a buffer.

     size_t              SoOutGetBufferSize(const SoOut *this)
          The total number of bytes allocated to a memory buffer may be larger
          than the number of bytes written. This returns that total number.

     void                SoOutResetBuffer(SoOut *this)
          Resets buffer for output again. Output starts over at beginning of
          buffer.

     void                SoOutSetBin(SoOut *this, SbBool flag)
          Sets whether output should be ASCII (default) or binary.

     SbBool              SoOutIsBin(const SoOut *this)
          Returns current state of binary flag.

     void                SoOutSetHdrStr(SoOut *this, const SbString *str)
          Sets the header for output files. This is useful, for example, if
          you have a file format that is a superset of the Inventor file
          format and you want Inventor to read the files. It is highly
          recommend that in your new header you simply append to the header of
          the Inventor file format you are extending. For example, if a new
          file format is based on the Inventor 2.1 file format, register a
          header similar to: "#Inventor V2.1 ascii MY FILE FORMAT EXTENSION"
          Then all Inventor 2.1 applications (and later) can read the file.

     void                SoOutResetHdrStr(SoOut *this)
          Resets the header for output files to be the default header.

     SbString            SoOutGetDfltASCIIHdr()
          Returns the string representing the default ASCII header.
     SbString            SoOutGetDfltBinHdr()
          Returns the string representing the default binary header.

     void                SoOutSetFltPrcsn(SoOut *this, int precision)
          Sets the precision for writing floating point numbers, i.e. the
          number of significant digits. Floating point numbers are written
          using %.xg format, where 'x' is the value of the precision argument.


SEE ALSO
     SoInput, SoWriteAction, SoTranSender