SoOutput(3)

📦

version 4.0.10 · 4 versions

4.0.10 · fedora 43, fedora 44 (latest)
4.0.10 · epel 9
4.0.3 · fedora 43
4.0.7 · fedora 44

💖 NAME 💖

SoOutput — bestie, this is the class that's basically an abstraction of an output stream. It writes stuff out. That's the whole vibe. ✨

📜 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 🌈

SoOutput is, like, the class that is an abstraction of an output stream. No cap.

It gives you the power to write basic types to a file or to a memory buffer, in ASCII or in binary format. Both. Your choice. Main character energy. 💖

See also: SoInput, SoWriteAction

🎀 MEMBER ENUMERATION DOCUMENTATION 🎀

`enum SoOutput::Stage`

This one lists out all the possible stages of a write operation — because writing needs to happen in multiple passes, okay? It's a whole process, not a one-and-done. 😌

See also: setStage(), getStage()

Enumerator

COUNT_REFS — bestie, we are not writing right now. We're just counting the internal references inside the scene graph. That's it. That's the task.
WRITE — ok so THIS is the one where the actual data export should take place during this pass. Periodt.

`enum SoOutput::Annotations`

The values in this enum get used for debugging purposes, to annotate the output from a write operation. iykyk. 🔍

Enumerator

ADDRESSES — annotates the output with pointer address information.
REF_COUNTS — annotates the output with reference counts of the objects that got written.

🦋 CONSTRUCTOR & DESTRUCTOR DOCUMENTATION 🦋

`SoOutput::SoOutput (void )`

The default constructor, slay. It makes an SoOutput instance that will write to the standard output.

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

`SoOutput::SoOutput (SoOutput * dictOut)`

Constructs an SoOutput that has a copy of the set of named references from dictOut. It's giving "borrowed your notes but made my own copy". 📝

`SoOutput::~SoOutput (void ) [virtual]`

Destructor. Say bye bestie. 👋

👑 MEMBER FUNCTION DOCUMENTATION 👑

`void SoOutput::setFilePointer (FILE * newFP) [virtual]`

Sets up a new file pointer that we're gonna write to.

Important note: do not use this method when the Coin library has been compiled as a Microsoft Windows DLL. 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. 💀 Not a vibe. Not fixable by us.

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

`FILE * SoOutput::getFilePointer (void ) const [virtual]`

Returns the current file pointer. If we're writing to a memory buffer, NULL gets returned instead.

Important note: same deal — do not use this method when the Coin library has been compiled as a Microsoft Windows DLL, because passing FILE* instances back or forth to DLLs is dangerous and will most likely cause a crash. Intrinsic Microsoft Windows DLL limitation, bestie. 🫠

See also: setFilePointer()

`SbBool SoOutput::openFile (const char *const fileName) [virtual]`

Opens a file for writing. If the file can't be opened or isn't writable, FALSE comes back at you.

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 gets deleted. She cleans up after herself. 💅

See also: setFilePointer(), setBuffer(), closeFile()

`void SoOutput::closeFile (void ) [virtual]`

Closes the currently opened file — but only if that file was passed to SoOutput through the openFile() method. If you handed it over some other way, it's not hers to close. Respect the boundaries. 🚫

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 and GZIP are the only compression methods supported, and you have to compile Coin with zlib and bzip2 support to enable them. No support, no squish. 🗜️

Supply compmethod = NONE or level = 0.0 if you want to disable compression. Compression is disabled by default.

Please note: it's not possible to compress when writing to a memory buffer. That's just not a thing.

This method returns TRUE if the compression method you picked is available. If it's not available, FALSE gets 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 gets stored in num. So you know exactly how many you're working with. 🔢

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 fills up, reallocFunc gets called to grab more memory. If reallocFunc returns NULL, further writing is disabled. That's the hard stop. 🛑

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's a good idea to make it a habit to always use getBuffer() to retrieve the memory buffer pointer after write operations. Don't be out here trusting the original pointer, bestie. 😭

Here's a complete, standalone usage example showing 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, "%s\n", 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 gets returned and the other return values will be undefined. So like, don't count on them. 🙈

See also: getBufferSize()

`size_t SoOutput::getBufferSize (void ) const [virtual]`

Returns the total size of the memory buffer. The whole thing. Every byte. 📏

See also: getBuffer()

`void SoOutput::resetBuffer (void ) [virtual]`

Resets the memory buffer write pointer back to the beginning of the buffer. Rewind, bestie. ⏪

`void SoOutput::setBinary (const SbBool flag) [virtual]`

Sets whether or not to write the output as a binary stream. You decide. 👑

See also: isBinary()

`SbBool SoOutput::isBinary (void ) const [virtual]`

Returns a flag that tells you whether or not we're writing the output as a binary stream.

See also: setBinary()

`void SoOutput::setHeaderString (const SbString & str) [virtual]`

Sets the output file header string. That first line of the file? Yours now. ✍️

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

`void SoOutput::resetHeaderString (void ) [virtual]`

Resets the header string back to the default one. Undo button, but for headers. 🎀

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

`void SoOutput::setFloatPrecision (const int precision)` [virtual]

Bestie, this is the glow-up knob for your floaty little numbers. It sets the precision used when writing floating point numbers out to ASCII files. <yellow>precision</yellow> should sit between 0 and 8 — no wildin' outside that range, okay? And heads up: the double precision gets set to precision * 2. ✨

`void SoOutput::setStage (Stage stage)`

Sets an indicator on the current stage. Why do we even need stages? Because the writing has to happen in multiple passes to account for the export of references/connections within the scene graphs. It's giving multi-step skincare routine, not one-and-done. 🧖

This method is basically just used from within SoWriteAction, and it should usually not be of interest to the application programmer.

⚠️ Do not use it unless you really know what you are doing. Like, really really. 💀

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. Two passes, one iconique output. 💅

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. Cute lil staircase moment. 🪜

See also: decrementIndent(), indent()

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

Decrease indentation level in the file. Going back down the stairs, no drama. 🌸

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. Alignment queen behavior, no cap. 👑

`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. Two vibes, one function. 🦋

`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. Same energy, unsigned edition. 💜

`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. And here's the plot twist: if we're writing in ASCII format, the value will be written in base 16 (hexadecimal). Slay. 🔥

`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. Raw bytes, going straight to their destination, main character energy. ✨

`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. Pretty-printing is self-care, fr fr. 🎀

See also: incrementIndent(), decrementIndent()

`void SoOutput::reset (void )` [virtual]

Reset all value and make ready for using another file pointer or buffer. Wipe the slate, fresh start, new era. 🧚

`void SoOutput::setCompact (SbBool flag)`

Set up the output to be more compact than with the default write routines. Less whitespace, more efficiency, it's giving minimalism. 💅

`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. Bestie, do not get it twisted.

`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. Lowkey a debug-only situation. 🦋

`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. Every base gets its own little ID card. 🪪

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

Returns the unique identifier for base or -1 if not found. If they're not in the book, they get a -1, periodt. 💅

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

Sets the reference for base manually. Manual override moment. 🔥

`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. Vibe check: already in the club? ✨

`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. Recycling the name tag, sustainability queen. 🌸