SoOutput.h

/*=======================================================================
 * Copyright 1991-1996, Silicon Graphics, Inc.
 * ALL RIGHTS RESERVED
 *
 * UNPUBLISHED -- Rights reserved under the copyright laws of the United
 * States.   Use of a copyright notice is precautionary only and does not
 * imply publication or disclosure.
 *
 * U.S. GOVERNMENT RESTRICTED RIGHTS LEGEND:
 * Use, duplication or disclosure by the Government is subject to restrictions
 * as set forth in FAR 52.227.19(c)(2) or subparagraph (c)(1)(ii) of the Rights
 * in Technical Data and Computer Software clause at DFARS 252.227-7013 and/or
 * in similar or successor clauses in the FAR, or the DOD or NASA FAR
 * Supplement.  Contractor/manufacturer is Silicon Graphics, Inc.,
 * 2011 N. Shoreline Blvd. Mountain View, CA 94039-7311.
 *
 * THE CONTENT OF THIS WORK CONTAINS CONFIDENTIAL AND PROPRIETARY
 * INFORMATION OF SILICON GRAPHICS, INC. ANY DUPLICATION, MODIFICATION,
 * DISTRIBUTION, OR DISCLOSURE IN ANY FORM, IN WHOLE, OR IN PART, IS STRICTLY
 * PROHIBITED WITHOUT THE PRIOR EXPRESS WRITTEN PERMISSION OF SILICON
 * GRAPHICS, INC.
**=======================================================================*/
/*=======================================================================
** Author      : Paul S. Strauss (MMM yyyy)
** Modified by : Gavin Bell (MMM yyyy)
**=======================================================================*/
/*=======================================================================
 *** THE CONTENT OF THIS WORK IS PROPRIETARY TO FEI S.A.S, (FEI S.A.S.),            ***
 ***              AND IS DISTRIBUTED UNDER A LICENSE AGREEMENT.                     ***
 ***                                                                                ***
 ***  REPRODUCTION, DISCLOSURE,  OR USE,  IN WHOLE OR IN PART,  OTHER THAN AS       ***
 ***  SPECIFIED  IN THE LICENSE ARE  NOT TO BE  UNDERTAKEN  EXCEPT WITH PRIOR       ***
 ***  WRITTEN AUTHORIZATION OF FEI S.A.S.                                           ***
 ***                                                                                ***
 ***                        RESTRICTED RIGHTS LEGEND                                ***
 ***  USE, DUPLICATION, OR DISCLOSURE BY THE GOVERNMENT OF THE CONTENT OF THIS      ***
 ***  WORK OR RELATED DOCUMENTATION IS SUBJECT TO RESTRICTIONS AS SET FORTH IN      ***
 ***  SUBPARAGRAPH (C)(1) OF THE COMMERCIAL COMPUTER SOFTWARE RESTRICTED RIGHT      ***
 ***  CLAUSE  AT FAR 52.227-19  OR SUBPARAGRAPH  (C)(1)(II)  OF  THE RIGHTS IN      ***
 ***  TECHNICAL DATA AND COMPUTER SOFTWARE CLAUSE AT DFARS 52.227-7013.             ***
 ***                                                                                ***
 ***                   COPYRIGHT (C) 1996-2024 BY FEI S.A.S,                        ***
 ***                        BORDEAUX, FRANCE                                        ***
 ***                      ALL RIGHTS RESERVED                                       ***
**=======================================================================*/
/*=======================================================================
** Modified by : VSG (MMM YYYY)
**=======================================================================*/
 
 
#ifndef  _SO_OUTPUT_
#define  _SO_OUTPUT_
 
#include <Inventor/misc/SoBasic.h>
#include <Inventor/SbDict.h>
#include <Inventor/SbString.h>
#include <Inventor/SoType.h>
 
class SoBase;
class SoOutputImpl;
 
typedef void *SoOutputReallocCB(void *ptr, size_t newSize);
 
//
//  Class: SoOutput
//
//  This file contains the definition of the SoOutput (output stream)
//  class. This class is used for writing Inventor data files; it
//  supports both ASCII (default) and binary formats and provides some
//  convenience functions for handling files. It also supports easy
//  indentation.
//
//  Output can go to: (1) a file pointer created by the caller, (2) a
//  file opened by SoOutput, or (3) a buffer in memory created by the
//  caller. In the third case, the caller supplies a pointer to the
//  buffer, the initial size of the buffer, and a reallocation
//  function to call when that size is exceeded. At any time during
//  the writing, the caller can inquire the address of the buffer and
//  how many bytes have been inserted into it.
//
//  SoOutput support data compression on the fly. When the file is opened
//  by SoOutput the file can be compressed.
//
//  SoOutput also contains a dictionary that correlates node and path
//  pointers to temporary names written to files. This is so
//  references to previously defined nodes and paths are written
//  correctly.
//
 
class  SoOutput {
 public:
 
  SoOutput();
 
  virtual ~SoOutput();
 
  enum FileProperty
  {
    DefaultProperty = 0,
    CompressedZlib = 1
  };
 
   virtual void setFileProperty( const FileProperty properties );
 
   FileProperty getFileProperty() const;
 
  virtual void                setFilePointer(FILE *newFP);
 
  virtual FILE *              getFilePointer() const;
 
  size_t fileWrite( void* buffer, size_t elemSize, size_t count );
 
  int filePuts( const char* );
 
  int filePutc( int );
 
  SoNONUNICODE virtual SbBool              openFile(const char *fileName);
 
  virtual SbBool              openFile( const SbString& fileName );
 
  virtual void                closeFile();
 
  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() const { return bufSize; }
 
  virtual void                resetBuffer();
 
  virtual void                setBinary(SbBool flag);
 
  virtual SbBool              isBinary() const                { return binary; }
 
  SbBool                      isWritingForScaleViz() const;
 
  virtual void                setHeaderString(const SbString &str);
  virtual void                resetHeaderString();
 
  static SbString     getDefaultASCIIHeader();
  static SbString     getDefaultBinaryHeader();
 
  virtual void                setFloatPrecision(int precision);
 
  virtual void                setDoublePrecision(int precision);
 
 
 private:
 
#ifdef _WIN32
  virtual SbBool      openFromHandle(UINT hFile);
#endif
  virtual void                flushFile();
 
  // Enum that determines stage of operation of writing
  enum Stage {
    COUNT_REFS,             // Count write references
    WRITE                   // Actually write to file
  };
 
  // Sets/returns current stage of operation of action
  void                setStage(Stage stage)           { curStage = stage; }
  Stage               getStage() const                { return curStage; }
 
  // Increments/decrements indentation level by amount (default 1).
  // Each indentation level is 4 spaces.
  void                incrementIndent(int amount = 1)
    { indentLevel += amount; }
  void                decrementIndent(int amount = 1)
    { indentLevel -= amount; }
 
  int                 getIndentLevel(){ return indentLevel; }
 
  // Writes item of particular type to current file pointer/buffer
  virtual void                write(bool           b);
  virtual void                write(char           c);
  virtual void                write(unsigned char  c);
  virtual void                write(const char    *s);
  virtual void                write(const SbString &s);
  virtual void                write(const SbName   &n);
  virtual void                write(int32_t i);
  virtual void                write(int64_t i);
  virtual void                write(uint32_t i);
  virtual void                write(uint64_t i);
  virtual void                write(short          s);
  virtual void                write(unsigned short s);
  virtual void                write(float          f);
  virtual void                write(double         d);
  virtual void                writeBinaryArray(unsigned char *c, int length);
  virtual void                writeBinaryArray(int32_t *l, int length);
  virtual void                writeBinaryArray(int64_t *l, int length);
  virtual void                writeBinaryArray(float *f, int length);
  virtual void                writeBinaryArray(double *d, int length);
  virtual void                writeBinaryArray(short *s, int length);
 
  // Writes indentation to file/buffer based on current indentation level
  virtual void                indent();
 
 private:
 
  SbBool                      isOutFileVRML2() { return vrmlFileOut;}
  SbBool                      isOutFileX3D() { return x3dFileOut;}
  SbBool                      isHeaderWritten() { return wroteHeader;}
  void                        incrementRefOut(int amount = 1)
    { refOut += amount; }
  int                         getRefOut() { return refOut;}
  // Constructor that gets reference dictionary from another SoOutput
  SoOutput(SoOutput *dictOut);
 
  virtual void                writeLargeBinaryArray(unsigned char *c, size_t length);
 
  // Resets things for writing to a new file or changing files
  virtual void                reset();
 
  // Prevents header and extra white space from being written.
  // Useful for producing compact strings of data.
  void                setCompact(SbBool flag)         { compact = flag; }
  SbBool              isCompact() const               { return compact; }
 
  // Bit mask for various output annotations.  Note that annotation is
  // automatically disabled for non-compact or binary format.
  enum Annotations {
    ADDRESSES  = (1<<0),    // pointer values
    REF_COUNTS = (1<<1)     // node reference counts
  };
  void                setAnnotation(uint32_t bits)
    { annotation = bits; }
  uint32_t            getAnnotation()
    { return (isCompact() || isBinary()) ? 0 : annotation; }
  SbPList             routeList;      // List of connections so route's
  //  can be written to a file
  // Looks up a reference, returning the reference id or -1 if it
  // hasn't been added yet.
  int                 findReferenceIfVRML2(const SoBase *base) const;
  // Adds a reference to dictionary, returning the reference id
  // created for it.
  int                 addReferenceIfVRML2(const SoBase *base);
 
  // Adds a reference to dictionary in current file.
  virtual void      addToVRML2Dict(const SbString name, const SoBase *base);
 
  // Looks up a reference, returning the name for this base pointer or NULL
  virtual  SoBase *    findInVRML2Dict( const SbString name) const;
 
  // Adds a reference to dictionary in current file.
  virtual void        addToVRMLName(const SoBase *base, const char *name);
 
  // Writes correct file header string to current file/buffer
  void                writeHeader();
  // Looks up a reference, returning the name for this base pointer or NULL
  virtual  char *     findInVRMLName( const  SoBase *base) const;
  SbDict              *refVRMLName;   // SoBase pointer -> write name
  SbDict              *refVRML2;      // SoBase pointer -> write name
  SbDict              *PROTOToWrite;  // SoBase pointer -> write name
  int                  refOut;
 
  int32_t isWritingBinArrayAsMemObj() const;
 
  SoOutputImpl* m_soOutputImpl;
 
  struct SoOutputEntry {
    SbName      name;       // Name of output
    int64_t     offset;     // Offset of output within object
    SoType type;            // Type of output
  };
 
  // Extracts the file version if the header string isn't empty.
  // Otherwise it returns the current file version.
  float getIVVersion();
 
 private:
  FILE                *fp;            // File writing to
  void                *zFp;           // gzip file pointer
  SbBool              toBuffer;       // TRUE if writing to buffer
  char                *tmpBuffer;     // For binary write to file
  void                *buffer;        // Buffer writing to
  char                *curBuf;        // Current pointer in buffer
  size_t              bufSize;        // Maximum buffer size
  size_t              tmpBufSize;     // Maximum temporary buffer size
  SoOutputReallocCB   *reallocFunc;   // Reallocation function for buffer
  SbBool              openedHere;     // TRUE if SoOutput opened file
  SbBool              openedFromHandle; // TRUE if opened from Win32 file handle
  SbBool              binary;         // TRUE if writing binary data
  SbBool              compact;        // TRUE if writing in compact form
  SbBool              wroteHeader;    // TRUE if header was written
  int                 indentLevel;    // Current indentation level
  SbDict              *refDict;       // SoBase pointer -> reference ID
  SbBool              borrowedDict;   // TRUE if dict from another SoOutput
  int                 refIdCount;     // Counter for generating ref IDs
  SbBool              anyRef;         // TRUE if any reference in dictionary
  uint32_t            annotation;     // annotation bit mask
  Stage               curStage;       // Stage of operation
  SbString            headerString;   // The header
  FileProperty        m_fileProperties; // File properties (like compression...)
 
  // Pad a header so that it is correctly aligned for reading from
  // binary files into memory
  static SbString     padHeader(const SbString &inString);
 
  // Returns TRUE if writing into memory buffer rather than file
  SbBool              isToBuffer() const
    { return toBuffer; }
 
  virtual SbBool setupFileProperties();
 
  // Returns number of bytes in current buffer
  size_t              bytesInBuf() const
    { return (curBuf - static_cast<char *>(buffer) ); }
 
  // Makes sure current buffer can contain nBytes more bytes
  SbBool              makeRoomInBuf(size_t nBytes);
 
  // Makes sure temporary buffer can contain nBytes more bytes
  SbBool              makeRoomInTmpBuf(size_t nBytes);
 
  // Adds a reference to dictionary, returning the reference id
  // created for it.
  int                 addReference(const SoBase *base);
 
  // Looks up a reference, returning the reference id or -1 if it
  // hasn't been added yet.
  int                 findReference(const SoBase *base) const;
 
  // Convert datatypes to network format during writing
  void                convertShort(short s, char *to);
  void                convertInt32(int32_t l, char *to);
  void                convertInt64(int64_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                convertInt64Array( int64_t *from, char *to, int len);
  void                convertFloatArray( float *from, char *to, int len);
  void                convertDoubleArray( double *from, char *to, int len);
  
  const char* getDoublesFormatString() const;
 
  const char* getFloatsFormatString() const;
 
 
  SbBool              vrmlFileOut;
  SbBool              x3dFileOut;
  float m_ivVersion;
 
  private:
  char                m_floatsFmtString[16];  // Output format for floats
  char                m_doublesFmtString[16];  // Output format for doubles
 
 
  friend class SoBase;
  friend class SoDB;
};
 
#endif /* _SO_OUTPUT_ */