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 *const fileName) [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 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’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_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, 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 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 filepointer 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 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_t bits) 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, 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 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_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 realloction 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.