Coin  4.0.3
Coin3D core library
Loading...
Searching...
No Matches
SoOutput Class Reference

The SoOutput class is an abstraction of an output stream. More...

#include <Inventor/SoOutput.h>

Public Types

enum  Annotations { ADDRESSES = 0x01 , REF_COUNTS = 0x02 }
 
enum  Stage { COUNT_REFS , WRITE }
 

Public Member Functions

 SoOutput (SoOutput *dictOut)
 
 SoOutput (void)
 
virtual ~SoOutput ()
 
void addDEFNode (SbName name)
 
int addReference (const SoBase *base)
 
void addRoute (SoFieldContainer *from, const SbName &fromfield, SoFieldContainer *to, const SbName &tofield)
 
virtual void closeFile (void)
 
void decrementIndent (const int levels=1)
 
int findReference (const SoBase *base) const
 
uint32_t getAnnotation (void)
 
virtual SbBool getBuffer (void *&bufPointer, size_t &nBytes) const
 
virtual size_t getBufferSize (void) const
 
SoProtogetCurrentProto (void) const
 
virtual FILEgetFilePointer (void) const
 
Stage getStage (void) const
 
void incrementIndent (const int levels=1)
 
virtual void indent (void)
 
virtual SbBool isBinary (void) const
 
SbBool isCompact (void) const
 
SbBool lookupDEFNode (SbName name)
 
virtual SbBool openFile (const char *const fileName)
 
void popProto (void)
 
void pushProto (SoProto *proto)
 
void removeDEFNode (SbName name)
 
virtual void reset (void)
 
virtual void resetBuffer (void)
 
virtual void resetHeaderString (void)
 
void resolveRoutes (void)
 
void setAnnotation (uint32_t bits)
 
virtual void setBinary (const SbBool flag)
 
virtual void setBuffer (void *bufPointer, size_t initSize, SoOutputReallocCB *reallocFunc, int32_t offset=0)
 
void setCompact (SbBool flag)
 
SbBool setCompression (const SbName &compmethod, const float level=0.5f)
 
virtual void setFilePointer (FILE *newFP)
 
virtual void setFloatPrecision (const int precision)
 
virtual void setHeaderString (const SbString &str)
 
void setReference (const SoBase *base, int refid)
 
void setStage (Stage stage)
 
virtual void write (const char *s)
 
virtual void write (const char c)
 
virtual void write (const double d)
 
virtual void write (const float f)
 
virtual void write (const int i)
 
virtual void write (const SbName &n)
 
virtual void write (const SbString &s)
 
virtual void write (const short s)
 
virtual void write (const unsigned int i)
 
virtual void write (const unsigned short s)
 
virtual void writeBinaryArray (const double *const d, const int length)
 
virtual void writeBinaryArray (const float *const f, const int length)
 
virtual void writeBinaryArray (const int32_t *const l, const int length)
 
virtual void writeBinaryArray (const unsigned char *c, const int length)
 

Static Public Member Functions

static const SbNamegetAvailableCompressionMethods (unsigned int &num)
 
static SbString getDefaultASCIIHeader (void)
 
static SbString getDefaultBinaryHeader (void)
 

Protected Member Functions

size_t bytesInBuf (void) const
 
void convertDouble (double d, char *to)
 
void convertDoubleArray (double *from, char *to, int len)
 
void convertFloat (float f, char *to)
 
void convertFloatArray (float *from, char *to, int len)
 
void convertInt32 (int32_t l, char *to)
 
void convertInt32Array (int32_t *from, char *to, int len)
 
void convertShort (short s, char *to)
 
void convertShortArray (short *from, char *to, int len)
 
SbBool isToBuffer (void) const
 
SbBool makeRoomInBuf (size_t nBytes)
 

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

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

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

Constructor & Destructor Documentation

◆ SoOutput() [1/2]

SoOutput::SoOutput ( void )

The default constructor makes an SoOutput instance which will write to the standard output.

See also
setFilePointer(), openFile(), setBuffer()

◆ SoOutput() [2/2]

SoOutput::SoOutput ( SoOutput * dictOut)

Constructs an SoOutput which has a copy of the set of named references from dictOut.

◆ ~SoOutput()

SoOutput::~SoOutput ( void )
virtual

Destructor.

Member Function Documentation

◆ addDEFNode()

void SoOutput::addDEFNode ( SbName name)

Adds name to the set of currently DEF'ed node names so far in the output process.

◆ addReference()

int SoOutput::addReference ( const SoBase * base)

Makes a unique id for base and adds a mapping into our dictionary.

◆ addRoute()

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

◆ bytesInBuf()

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.

◆ 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()

◆ convertDouble()

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()

◆ convertDoubleArray()

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

◆ convertFloat()

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()

◆ convertFloatArray()

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

◆ convertInt32()

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()

◆ convertInt32Array()

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

◆ convertShort()

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()

◆ convertShortArray()

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

◆ decrementIndent()

void SoOutput::decrementIndent ( const int levels = 1)

Decrease indentation level in the file.

See also
incrementIndent(), indent()

◆ findReference()

int SoOutput::findReference ( const SoBase * base) const

Returns the unique identifier for base or -1 if not found.

◆ getAnnotation()

uint32_t SoOutput::getAnnotation ( void )

Returns the current annotation debug bitflag settings.

◆ getAvailableCompressionMethods()

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

◆ getBuffer()

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()

◆ getBufferSize()

size_t SoOutput::getBufferSize ( void ) const
virtual

Returns total size of memory buffer.

See also
getBuffer()

◆ getCurrentProto()

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

◆ getDefaultASCIIHeader()

SbString SoOutput::getDefaultASCIIHeader ( void )
static

Return the default header string written to ASCII files.

See also
setHeaderString(), resetHeaderString(), getDefaultBinaryHeader()

◆ getDefaultBinaryHeader()

SbString SoOutput::getDefaultBinaryHeader ( void )
static

Return the default header string written to binary files.

See also
setHeaderString(), resetHeaderString(), getDefaultASCIIHeader()

◆ 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()

◆ 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()

◆ incrementIndent()

void SoOutput::incrementIndent ( const int levels = 1)

Increase indentation level in the file.

See also
decrementIndent(), indent()

◆ indent()

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()

◆ 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()

◆ isCompact()

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.

◆ isToBuffer()

SbBool SoOutput::isToBuffer ( void ) const
protected

Returns TRUE if we're set up to write to a memory buffer.

◆ lookupDEFNode()

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.

◆ makeRoomInBuf()

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.

◆ openFile()

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()

◆ padHeader()

SbString SoOutput::padHeader ( const SbString & inString)
staticprotected

Pads the header we're writing so it contains the correct amount of bytes for the alignment of the following binary writes.

◆ popProto()

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

◆ pushProto()

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

◆ removeDEFNode()

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.

◆ reset()

void SoOutput::reset ( void )
virtual

Reset all value and make ready for using another file pointer or buffer.

◆ resetBuffer()

void SoOutput::resetBuffer ( void )
virtual

Reset the memory buffer write pointer back to the beginning of the buffer.

◆ resetHeaderString()

void SoOutput::resetHeaderString ( void )
virtual

Reset the header string to the default one.

See also
setHeaderString(), getDefaultASCIIHeader(), getDefaultBinaryHeader()

◆ resolveRoutes()

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

◆ setAnnotation()

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.

◆ setBinary()

void SoOutput::setBinary ( const SbBool flag)
virtual

Set whether or not to write the output as a binary stream.

See also
isBinary()

◆ setBuffer()

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 <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 = (char *)malloc(1024);
buffer_size = 1024;
out.setBuffer(buffer, buffer_size, buffer_realloc);
wa.apply(root);
SbString s(buffer);
free(buffer);
return s;
}
int
main(int argc, char ** argv)
{
SoSeparator * root = new SoSeparator;
root->ref();
root->addChild(new SoCone);
(void)fprintf(stdout, "%s\n", s.getString());
root->unref();
return 0;
}
The SbList class is a template container class for lists.
Definition SbList.h:70
The SbString class is a string class with convenience functions for string operations.
Definition SbString.h:52
const char * getString(void) const
Definition SbString.h:84
void unref(void) const
Definition SoBase.cpp:530
void ref(void) const
Definition SoBase.cpp:478
The SoCone class is for rendering cone shapes.
Definition SoCone.h:41
static void init(void)
Definition SoDB.cpp:200
virtual void addChild(SoNode *node)
Definition SoGroup.cpp:453
The SoNode class is the base class for nodes used in scene graphs.
Definition SoNode.h:56
The SoOutput class is an abstraction of an output stream.
Definition SoOutput.h:51
The SoSeparator class is a state-preserving group node.
Definition SoSeparator.h:44
The SoWriteAction class writes a scene graph to file.
Definition SoWriteAction.h:42
See also
getBuffer(), getBufferSize(), resetBuffer()

◆ setCompact()

void SoOutput::setCompact ( SbBool flag)

Set up the output to be more compact than with the default write routines.

◆ setCompression()

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

◆ setFilePointer()

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()

◆ setFloatPrecision()

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.

◆ setHeaderString()

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

Set the output file header string.

See also
resetHeaderString(), getDefaultASCIIHeader(), getDefaultBinaryHeader()

◆ setReference()

void SoOutput::setReference ( const SoBase * base,
int refid )

Sets the reference for base manually.

◆ setStage()

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()

◆ write() [1/10]

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.

◆ write() [2/10]

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.

◆ write() [3/10]

void SoOutput::write ( const double d)
virtual

Write d as a character string.

◆ write() [4/10]

void SoOutput::write ( const float f)
virtual

Write f as a character string.

◆ write() [5/10]

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.

◆ write() [6/10]

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

◆ write() [7/10]

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

◆ write() [8/10]

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.

◆ write() [9/10]

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.

◆ write() [10/10]

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

◆ writeBinaryArray() [1/4]

void SoOutput::writeBinaryArray ( const double *const d,
const int length )
virtual

Write an array of double values in binary format.

◆ writeBinaryArray() [2/4]

void SoOutput::writeBinaryArray ( const float *const f,
const int length )
virtual

Write an array of float values in binary format.

◆ writeBinaryArray() [3/4]

void SoOutput::writeBinaryArray ( const int32_t *const l,
const int length )
virtual

Write an length array of int32_t values in binary format.

◆ writeBinaryArray() [4/4]

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.

Member Data Documentation

◆ wroteHeader

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.


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