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 = new SoWriteAction()  ;
writeAction.GetOutput().OpenFile( "output.iv" );
writeAction.Apply( root );
writeAction.GetOutput().CloseFile();

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

X3D / VRML Open Inventor ASCII format is essentially the same as the VRML97 format (because the standard was influenced by Open Inventor), which is now called the "Classic VRML" encoding in the X3D specification (see www.x3d.org). The main difference is the file header. If you need to write VRML compatible files, you must set the appropriate file header using the setHeaderString() method, for example: VRML97: "#VRML V2.0 utf8" X3D : "#X3D V3.0 utf8" When an X3D header string has been set, Open Inventor will automatically write "PROFILE Core" as the next line after the file header. However setting the correct header string does not guarantee everything in the file is valid X3D/VRML. If you need to convert a scene graph containing Open Inventor specific nodes to X3D/VRML, use SoToVRML2Action.

VRML format files were traditionally given the extension ".wrl", but X3D now specifies the extension ".x3dv" for Classic VRML format files. Compressed VRML format files were traditionally given the extension ".wrz" or ".wrl.gz", but X3D now specifies the extension ".x3dvz" or ".x3dv.gz". VRML format files can only be written in ASCII.

Reference