Open Inventor Release 2024.1.1
 
Loading...
Searching...
No Matches
SoOutput Class Reference

Used to write Open Inventor data files. More...

#include <Inventor/SoOutput.h>

Public Types

enum  FileProperty {
  DefaultProperty = 0 ,
  CompressedZlib = 1
}
 This enum defines the properties used when data are written to a file. More...
 
typedef void * SoOutputReallocCB(void *ptr, size_t newSize)
 

Public Member Functions

 SoOutput ()
 Constructor.
 
virtual ~SoOutput ()
 Destructor.
 
virtual void setFileProperty (const FileProperty properties)
 Sets a combination of properties for the current file.
 
FileProperty getFileProperty () const
 Returns the current properties used by SoOutput.
 
virtual void setFilePointer (FILE *newFP)
 Sets file pointer to write to.
 
virtual FILE * getFilePointer () const
 Returns the file pointer in use, or NULL if using a buffer.
 
size_t fileWrite (void *buffer, size_t elemSize, size_t count)
 Write a buffer to the currently open file.
 
int filePuts (const char *)
 Write a string to the currently open file.
 
int filePutc (int)
 Write a byte to the currently open file.
 
virtual SoNONUNICODE SbBool openFile (const char *fileName)
 Opens named file, sets current file to result.
 
virtual SbBool openFile (const SbString &fileName)
 Opens named file, sets current file to result.
 
virtual void closeFile ()
 Closes current file if opened with openFile().
 
virtual void setBuffer (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.
 
virtual SbBool getBuffer (void *&bufPointer, size_t &nBytes) const
 Returns memory buffer being written to and the new size of the buffer.
 
virtual size_t getBufferSize () const
 The total number of bytes allocated to a memory buffer may be larger than the number of bytes written.
 
virtual void resetBuffer ()
 Resets buffer for output again.
 
virtual void setBinary (SbBool flag)
 Sets whether output should be ASCII (default) or binary.
 
virtual SbBool isBinary () const
 Returns current state of binary flag.
 
SbBool isWritingForScaleViz () const
 Returns TRUE if ScaleViz is currently writing data for synchronization.
 
virtual void setHeaderString (const SbString &str)
 Sets the header for output files.
 
virtual void resetHeaderString ()
 Resets the header for output files to be the default header.
 
virtual void setFloatPrecision (int precision)
 Sets the precision for writing floating point numbers (type float), i.e. the number of significant digits.
 
virtual void setDoublePrecision (int precision)
 Sets the precision for writing floating point numbers (type double), i.e. the number of significant digits.
 

Static Public Member Functions

static SbString getDefaultASCIIHeader ()
 Returns the string representing the default ASCII header.
 
static SbString getDefaultBinaryHeader ()
 Returns the string representing the default binary header.
 

Friends

class SoBase
 
class SoDB
 

Detailed Description

Used to write Open Inventor data files.

This class is used for writing Open Inventor data files. It supports both ASCII (default) and binary formats and provides some convenience functions for opening and closing files. See SbFileHelper for more convenience functions. It can write to a buffer in memory as well as to a file. Since Open Inventor 8.1, SoOutput can write compressed data in the lossless Zlib (aka gzip) format. Both ASCII and binary format files may be compressed.

An instance of SoOutput is automatically created by SoWriteAction and can be queried using the getOutput() method in that class. This is typically the only instance needed. For example:

SoWriteAction writeAction;
writeAction.getOutput()->openFile( "output.iv" );
writeAction.apply( scene );
writeAction.getOutput()->closeFile();
virtual void apply(SoNode *node)
Initiates an action on the graph defined by a node.
virtual SoNONUNICODE SbBool openFile(const char *fileName)
Opens named file, sets current file to result.
virtual void closeFile()
Closes current file if opened with openFile().
Writes a scene graph to a file.
SoOutput * getOutput() const
Returns reference to SoOutput instance in action.

Note that file properties (binary, compression, header string, etc) should be set before calling openFile() or setFilePointer().

File extensions
The recommended file extension for Open Inventor format files, both ASCII and binary is ".iv". Open Inventor will automatically detect if the file is ASCII or binary based on the file header string. Compressed Open Inventor files may be given the extension ".ivz" for convenience, but it is not required. Open Inventor automatically detects compressed files.

File Header
Open Inventor writes a human readable file header as the first line of both ASCII and binary format files. Since Open Inventor 8.0, the default file header looks like this:
ASCII : "#Inventor V8.0 ascii"
Binary: "#Inventor V8.0 binary LE"
The two character code at the end of the binary header indicates if the file was written on a little-endian (LE) or big-endian (BE) machine. The version number string may change again in the future if incompatible changes are made to the file format. You can always query the current default headers using static methods getDefaultASCIIHeader() and getDefaultBinaryHeader().

All versions of Open Inventor from version 2.1 through version 7.x, wrote the version number string "V2.1" by default and did not append "LE" (or "BE") to the binary header. Open Inventor cannot, in general, load files containing a file header from a newer version. However all versions of Open Inventor can load files written by older versions and can load files containing the V2.1 file header. We recommend always using the default file header because newer versions enable performance enhancing features in the file format. If you need to write a file compatible with older versions, call setHeaderString() with "#Inventor V2.1 ascii" or "#Inventor V2.1 binary".

SEE ALSO

SoInput, SoWriteAction, SoTranSender, SbFileHelper

Definition at line 186 of file SoOutput.h.

Member Typedef Documentation

◆ SoOutputReallocCB

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

Definition at line 63 of file SoOutput.h.

Member Enumeration Documentation

◆ FileProperty

This enum defines the properties used when data are written to a file.

The function setFileProperty uses this enum.

Since Open Inventor 8.1

Enumerator
DefaultProperty 

Regular ascii or binary output.

This is the default property value.

CompressedZlib 

Compressed ascii or binary output using the zlib module.

Definition at line 205 of file SoOutput.h.

Constructor & Destructor Documentation

◆ SoOutput()

SoOutput::SoOutput ( )

Constructor.

The default SoOutput writes to stdout.

◆ ~SoOutput()

virtual SoOutput::~SoOutput ( )
virtual

Destructor.

The destructor closes any files opened by the SoOutput.

Member Function Documentation

◆ closeFile()

virtual void SoOutput::closeFile ( )
virtual

Closes current file if opened with openFile().

◆ filePutc()

int SoOutput::filePutc ( int  )

Write a byte to the currently open file.


If the file is compressed the byte is compressed on the fly. Returns -1 if no file is currently open. Returns EOF if an error occurs. Returns the byte value specified if successful.

Since Open Inventor 8.1

◆ filePuts()

int SoOutput::filePuts ( const char *  )

Write a string to the currently open file.


If the file is compressed the string is compressed on the fly. Returns -1 if no file is currently open. Returns EOF if an error occurs. Returns a non-negative value if successful (same as fputs).

Since Open Inventor 8.1

◆ fileWrite()

size_t SoOutput::fileWrite ( void *  buffer,
size_t  elemSize,
size_t  count 
)

Write a buffer to the currently open file.


If the file is compressed the buffer is compressed on the fly. Returns -1 if no file is currently open, else returns total number of elements successfully written (same as fwrite).

Since Open Inventor 8.1

◆ getBuffer()

virtual SbBool SoOutput::getBuffer ( void *&  bufPointer,
size_t &  nBytes 
) const
virtual

Returns memory buffer being written to and the new size of the buffer.

Returns FALSE if not writing into a buffer.

◆ getBufferSize()

virtual size_t SoOutput::getBufferSize ( ) const
inlinevirtual

The total number of bytes allocated to a memory buffer may be larger than the number of bytes written.

This returns that total number.

Definition at line 313 of file SoOutput.h.

◆ getDefaultASCIIHeader()

static SbString SoOutput::getDefaultASCIIHeader ( )
static

Returns the string representing the default ASCII header.

◆ getDefaultBinaryHeader()

static SbString SoOutput::getDefaultBinaryHeader ( )
static

Returns the string representing the default binary header.

◆ getFilePointer()

virtual FILE * SoOutput::getFilePointer ( ) const
virtual

Returns the file pointer in use, or NULL if using a buffer.

Using this function can be dangerous, for example when the output is compressed! In such case the compressed file can be corrupt!

◆ getFileProperty()

FileProperty SoOutput::getFileProperty ( ) const

Returns the current properties used by SoOutput.

Since Open Inventor 8.1

◆ isBinary()

virtual SbBool SoOutput::isBinary ( ) const
inlinevirtual

Returns current state of binary flag.

Definition at line 328 of file SoOutput.h.

◆ isWritingForScaleViz()

SbBool SoOutput::isWritingForScaleViz ( ) const

Returns TRUE if ScaleViz is currently writing data for synchronization.

◆ openFile() [1/2]

virtual SoNONUNICODE SbBool SoOutput::openFile ( const char *  fileName)
virtual

Opens named file, sets current file to result.

This returns FALSE on error.

Non Unicode: This function should not be used in a Unicode application.

◆ openFile() [2/2]

virtual SbBool SoOutput::openFile ( const SbString fileName)
virtual

Opens named file, sets current file to result.

This returns FALSE on error. If the file extension is .ivz the file is compressed so the compression module is initialized during the call to openFile.

◆ resetBuffer()

virtual void SoOutput::resetBuffer ( )
virtual

Resets buffer for output again.

Output starts over at beginning of buffer.

◆ resetHeaderString()

virtual void SoOutput::resetHeaderString ( )
virtual

Resets the header for output files to be the default header.

◆ setBinary()

virtual void SoOutput::setBinary ( SbBool  flag)
virtual

Sets whether output should be ASCII (default) or binary.

◆ setBuffer()

virtual void SoOutput::setBuffer ( void *  bufPointer,
size_t  initSize,
SoOutputReallocCB reallocFunc,
int32_t  offset = 0 
)
virtual

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.

◆ setDoublePrecision()

virtual void SoOutput::setDoublePrecision ( int  precision)
virtual

Sets the precision for writing floating point numbers (type double), i.e. the number of significant digits.

Floating point numbers are written using %.xg format, where 'x' is the value of the precision argument.

◆ setFilePointer()

virtual void SoOutput::setFilePointer ( FILE *  newFP)
virtual

Sets file pointer to write to.

◆ setFileProperty()

virtual void SoOutput::setFileProperty ( const FileProperty  properties)
virtual

Sets a combination of properties for the current file.

The function must be called before the output of any data. It can be called before the openFile or setFilePointer functions.

The default property is DefaultProperty when the SoOutput object is created.

Since Open Inventor 8.1

◆ setFloatPrecision()

virtual void SoOutput::setFloatPrecision ( int  precision)
virtual

Sets the precision for writing floating point numbers (type float), i.e. the number of significant digits.

Floating point numbers are written using %.xg format, where 'x' is the value of the precision argument.

◆ setHeaderString()

virtual void SoOutput::setHeaderString ( const SbString str)
virtual

Sets the header for output files.

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

Friends And Related Symbol Documentation

◆ SoBase

friend class SoBase
friend

Definition at line 598 of file SoOutput.h.

◆ SoDB

friend class SoDB
friend

Definition at line 599 of file SoOutput.h.


The documentation for this class was generated from the following file: