src/VrmlData/VrmlData_Scene.hxx

   1 // Created on: 2006-10-08
   2 // Created by: Alexander GRIGORIEV
   3 // Copyright (c) 2006-2014 OPEN CASCADE SAS
   4 //
   5 // This file is part of Open CASCADE Technology software library.
   6 //
   7 // This library is free software; you can redistribute it and/or modify it under
   8 // the terms of the GNU Lesser General Public License version 2.1 as published
   9 // by the Free Software Foundation, with special exception defined in the file
  10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  11 // distribution for complete text of the license and disclaimer of any warranty.
  12 //
  13 // Alternatively, this file may be used under the terms of Open CASCADE
  14 // commercial license or contractual agreement.
  15
  16 #ifndef VrmlData_Scene_HeaderFile
  17 #define VrmlData_Scene_HeaderFile
  18
  19 #include <VrmlData_ListOfNode.hxx>
  20 #include <VrmlData_MapOfNode.hxx>
  21 #include <VrmlData_ErrorStatus.hxx>
  22 #include <VrmlData_Geometry.hxx>
  23 #include <VrmlData_WorldInfo.hxx>
  24 #include <TopoDS_Shape.hxx>
  25 #include <Standard_OStream.hxx>
  26 #include <Standard_IStream.hxx>
  27 #include <TCollection_ExtendedString.hxx>
  28 #include <NCollection_IncAllocator.hxx>
  29 #include <Standard_Mutex.hxx>
  30 #include <VrmlData_DataMapOfShapeAppearance.hxx>
  31
  32 // resolve name collisions with X11 headers
  33 #ifdef Status
  34   #undef Status
  35 #endif
  36
  37 struct VrmlData_InBuffer;
  38
  39 /**
  40  * Block of comments describing class VrmlData_Scene
  41  */
  42
  43 class VrmlData_Scene
  44 {
  45  public:
  46   /**
  47    * Iterator type to get all contained Nodes one-by-one.
  48    */
  49   typedef VrmlData_ListOfNode::Iterator Iterator;
  50
  51   // ---------- PUBLIC METHODS ----------
  52
  53   /**
  54    * Constructor.
  55    */
  56   Standard_EXPORT VrmlData_Scene (const Handle(NCollection_IncAllocator)& = 0L);
  57
  58   /**
  59    * Query the status of the previous operation.
  60    * Normally it should be equal to VrmlData_StatusOK (no error).
  61    */
  62   inline VrmlData_ErrorStatus   Status      () const
  63   { return myStatus; }
  64
  65   /**
  66    * Add the given directory path to the list of VRML file search directories.
  67    * This method forms the list of directories ordered according to the
  68    * sequence of this method calls. When an Inline node is found, the URLs
  69    * in that node are matched with these directories.
  70    * The last (implicit) search directory is the current process directory
  71    * ("."). It takes effect if the list is empty or if there is no match with
  72    * exisiting directories.
  73    */
  74   Standard_EXPORT void          SetVrmlDir  (const TCollection_ExtendedString&);
  75
  76   /**
  77    * Set the scale factor that would be further used in methods
  78    * ReadReal, ReadXYZ and ReadXY. All coordinates, distances and sized are
  79    * multiplied by this factor during reading the data.
  80    */
  81   inline void                   SetLinearScale (const Standard_Real theScale)
  82   { myLinearScale = theScale; }
  83
  84   /**
  85    * Returns the directory iterator, to check the presence of requested VRML
  86    * file in each iterated directory.
  87    */
  88   inline NCollection_List<TCollection_ExtendedString>::Iterator
  89                                 VrmlDirIterator () const
  90   { return NCollection_List<TCollection_ExtendedString>::Iterator(myVrmlDir); }
  91
  92   /**
  93    * Iterator of Nodes
  94    */
  95   inline Iterator               GetIterator () const
  96   { return Iterator (myLstNodes); }
  97
  98   /**
  99    * Get the iterator of named nodes.
 100    */
 101   inline VrmlData_MapOfNode::Iterator
 102                                 NamedNodesIterator() const
 103   { return myNamedNodes; }
 104
 105   /**
 106    * Allocator used by all nodes contained in the Scene.
 107    */
 108   inline const Handle(NCollection_IncAllocator)&
 109                                 Allocator   () const
 110   { return myAllocator; }
 111
 112   /**
 113    * Add a Node. If theN belongs to another Scene, it is cloned.
 114    * <p>VrmlData_WorldInfo cannot be added, in this case the method
 115    * returns a NULL handle.
 116    */
 117   Standard_EXPORT const Handle(VrmlData_Node)&
 118                                 AddNode     (const Handle(VrmlData_Node)& theN,
 119                                              const Standard_Boolean isTopLevel
 120                                              = Standard_True);
 121
 122   /**
 123    * Find a node by its name.
 124    * @param theName
 125    *   Name of the node to find.
 126    * @param theType
 127    *   Type to match. If this value is NULL, the first found node with the
 128    *   given name is returned. If theType is given, only the node that has
 129    *   that type is returned.
 130    */
 131   Standard_EXPORT Handle(VrmlData_Node)
 132                                 FindNode    (const char * theName,
 133                                              const Handle(Standard_Type)&
 134                                                            theType = 0L) const;
 135
 136   /**
 137    * Find a node by its name.
 138    * @param theName
 139    *   Name of the node to search for.
 140    * @param theLocation
 141    *   Location of the found node with respect to the whole VRML shape.
 142    */
 143   Standard_EXPORT Handle(VrmlData_Node)
 144                                 FindNode(const char * theName,
 145                                          gp_Trsf&     theLocation) const;
 146
 147   /**
 148    * Export to text stream (file or else).
 149    * This method is protected by Mutex, it is not allowed to read/write
 150    * two VRML streams concurrently.
 151    * The stream should give as the first line the VRML header:
 152    * <code>
 153    *   #VRML V2.0 <encoding type> [optional comment] <line terminator>
 154    * </code>
 155    *
 156    */
 157   friend Standard_EXPORT Standard_OStream&
 158                                 operator << (Standard_OStream&      theOutput,
 159                                              const VrmlData_Scene&  theScene);
 160
 161   /**
 162    * Import from text stream (file or else).
 163    * This method is protected by Mutex, it is not allowed to read/write
 164    * two VRML streams concurrently.
 165    */
 166   Standard_EXPORT VrmlData_Scene& operator<<(Standard_IStream& theInput);
 167
 168   /**
 169    * Convert the scene to a Shape.
 170    */
 171   Standard_EXPORT               operator TopoDS_Shape () const;
 172
 173   /**
 174    * Convert the scene to a Shape, with the information on materials defined
 175    * for each sub-shape. This method should be used instead of TopoDS_Shape
 176    * explicit conversion operator when you need to retrieve the material
 177    * aspect for each face or edge in the returned topological object.
 178    * @param M
 179    *   Data Map that binds an Appearance instance to each created TFace or
 180    *   TEdge if the Appearance node is defined in VRML scene for that geometry.
 181    * @return
 182    *   TopoDS_Shape (Compound) holding all the scene, similar to the result of
 183    *   explicit TopoDS_Shape conversion operator.
 184    */
 185   Standard_EXPORT TopoDS_Shape  GetShape (VrmlData_DataMapOfShapeAppearance& M);
 186
 187   /**
 188    * Query the WorldInfo member.
 189    */
 190   Standard_EXPORT const Handle(VrmlData_WorldInfo)&
 191                                 WorldInfo() const;
 192
 193   /**
 194    * Read a VRML line. Empty lines and comments are skipped.
 195    * The processing starts here from theBuffer.LinePtr; if there is at least
 196    * one non-empty character (neither space nor comment), this line is used
 197    * without reading the next one.
 198    * @param theLine
 199    *   Buffer receiving the input line
 200    * @param theInput
 201    *   Input stream
 202    * @param theLen
 203    *   Length of the input buffer (maximal line length)
 204    */
 205   Standard_EXPORT static VrmlData_ErrorStatus
 206                                 ReadLine    (VrmlData_InBuffer& theBuffer);
 207
 208   /**
 209    * Read a singel word from the input stream, delimited by whitespace.
 210    */
 211   Standard_EXPORT static VrmlData_ErrorStatus
 212                                 ReadWord    (VrmlData_InBuffer&       theBuffer,
 213                                              TCollection_AsciiString& theStr);
 214
 215   /**
 216    * Diagnostic dump of the contents
 217    */
 218   Standard_EXPORT void          Dump        (Standard_OStream& theStream) const;
 219
 220   /**
 221    * Read one real value.
 222    */
 223   Standard_EXPORT VrmlData_ErrorStatus
 224                                 ReadReal    (VrmlData_InBuffer& theBuffer,
 225                                              Standard_Real&     theResult,
 226                                              Standard_Boolean   isApplyScale,
 227                                              Standard_Boolean   isOnlyPositive)
 228                                                                         const;
 229
 230   /**
 231    * Read one triplet of real values.
 232    */
 233   Standard_EXPORT VrmlData_ErrorStatus
 234                                 ReadXYZ     (VrmlData_InBuffer& theBuffer,
 235                                              gp_XYZ&            theXYZ,
 236                                              Standard_Boolean   isApplyScale,
 237                                              Standard_Boolean   isOnlyPositive)
 238                                                                         const;
 239
 240   /**
 241    * Read one doublet of real values.
 242    */
 243   Standard_EXPORT VrmlData_ErrorStatus
 244                                 ReadXY      (VrmlData_InBuffer& theBuffer,
 245                                              gp_XY&             theXYZ,
 246                                              Standard_Boolean   isApplyScale,
 247                                              Standard_Boolean   isOnlyPositive)
 248                                                                         const;
 249   /**
 250    * Read an array of integer indices, for IndexedfaceSet and IndexedLineSet.
 251    */
 252   Standard_EXPORT VrmlData_ErrorStatus
 253                                 ReadArrIndex(VrmlData_InBuffer& theBuffer,
 254                                              const Standard_Integer **& theArr,
 255                                              Standard_Size&             theNBl)
 256                                                                         const;
 257
 258   /**
 259    * Query the line where the error occurred (if the status is not OK)
 260    */
 261   inline Standard_Integer       GetLineError() const { return myLineError; }
 262
 263   /**
 264    * Store the indentation for VRML output.
 265    * @param nSpc
 266    *   number of spaces to insert at every indentation level
 267    */
 268   inline void                   SetIndent   (const Standard_Integer nSpc)
 269   { myIndent = nSpc; }
 270
 271   /**
 272    * Write a triplet of real values on a separate line.
 273    * @param theXYZ
 274    *   The value to be output.
 275    * @param isScale
 276    *   If True, then each component is divided by myLinearScale.
 277    * @param thePostfix
 278    *   Optional string that is added before the end of the line.
 279    */
 280   Standard_EXPORT VrmlData_ErrorStatus
 281                                 WriteXYZ    (const  gp_XYZ&         theXYZ,
 282                                              const Standard_Boolean isScale,
 283                                              const char           * thePostfix
 284                                                                     = 0L) const;
 285   /**
 286    * Write an array of integer indices, for IndexedFaceSet and IndexedLineSet.
 287    */
 288   Standard_EXPORT VrmlData_ErrorStatus
 289                                 WriteArrIndex(const char *          thePrefix,
 290                                               const Standard_Integer ** theArr,
 291                                               const Standard_Size       theNbBl)
 292                                                                         const;
 293
 294
 295   /**
 296    * Write a string to the output stream respecting the indentation. The string
 297    * can be defined as two substrings that will be separated by a space.
 298    * Each of the substrings can be NULL, then it is ignored. If both
 299    * are NULL, then a single newline is output (without indent).
 300    * @param theLine0
 301    *   The first part of string to output
 302    * @param theLine1
 303    *   The second part of string to output
 304    * @param theIndent
 305    *   - 0 value ignored.
 306    *   - negative decreases the current indent and then outputs.
 307    *   - positive outputs and then increases the current indent.
 308    * @return
 309    *   Error status of the stream, or a special error if myOutput == NULL.
 310    */
 311   Standard_EXPORT VrmlData_ErrorStatus
 312                                 WriteLine   (const char           * theLine0,
 313                                              const char           * theLine1=0L,
 314                                              const Standard_Integer theIndent
 315                                                                      = 0) const;
 316
 317   /**
 318    * Write the given node to output stream 'myOutput'.
 319    */
 320   Standard_EXPORT VrmlData_ErrorStatus
 321                                 WriteNode   (const char * thePrefix,
 322                                              const Handle(VrmlData_Node)&) const;
 323
 324   /**
 325    * Query if the current write operation is dummy, i.e., for the purpose of
 326    * collecting information before the real write is commenced.
 327    */
 328   inline Standard_Boolean       IsDummyWrite() const
 329   { return myOutput == 0L; }
 330
 331  private:
 332   // ---------- PRIVATE METHODS (PROHIBITED) ----------
 333   VrmlData_Scene (const VrmlData_Scene&);
 334   VrmlData_Scene& operator = (const VrmlData_Scene&);
 335
 336  protected:
 337   /**
 338    * Read whatever line from the input checking the istream flags.
 339    */
 340   Standard_EXPORT static VrmlData_ErrorStatus
 341                                 readLine    (VrmlData_InBuffer&     theBuffer);
 342
 343   /**
 344    * Read and verify the VRML header (the 1st line of the file)
 345    */
 346   Standard_EXPORT static VrmlData_ErrorStatus
 347                                 readHeader  (VrmlData_InBuffer&     theBuffer);
 348
 349   /**
 350    * Create the node.
 351    * @param theBuffer
 352    *   Input buffer from where the node is created
 353    * @param theNode
 354    *   Output parameter, contains the created node on exit
 355    * @param Type
 356    *   Node type to be checked. If it is NULL no type checking is done.
 357    *   Otherwise the created node is matched and an error is returned if
 358    *   no match detected.
 359    */
 360   Standard_EXPORT VrmlData_ErrorStatus
 361                                 createNode  (VrmlData_InBuffer&     theBuffer,
 362                                              Handle(VrmlData_Node)& theNode,
 363                                              const Handle(Standard_Type)& Type);
 364
 365   /**
 366    * Create a single Shape object from all geometric nodes in the list.
 367    */
 368   Standard_EXPORT static void   createShape (TopoDS_Shape&          outShape,
 369                                              const VrmlData_ListOfNode&,
 370                                              VrmlData_DataMapOfShapeAppearance*);
 371
 372
 373  private:
 374   // ---------- PRIVATE FIELDS ----------
 375   Standard_Real                                 myLinearScale;
 376   VrmlData_ListOfNode                           myLstNodes; ///! top-level nodes
 377   VrmlData_ListOfNode                           myAllNodes; ///! all nodes
 378   VrmlData_ErrorStatus                          myStatus;
 379   Handle(NCollection_IncAllocator)               myAllocator;
 380   Handle(VrmlData_WorldInfo)                     myWorldInfo;
 381   VrmlData_MapOfNode                            myNamedNodes;
 382
 383   // read from stream
 384   NCollection_List<TCollection_ExtendedString>  myVrmlDir;
 385   Standard_Mutex                                myMutex;
 386   Standard_Integer                              myLineError;///! #0 if error
 387
 388   // write to stream
 389   Standard_OStream                              * myOutput;
 390   Standard_Integer                              myIndent;
 391   Standard_Integer                              myCurrentIndent;
 392   /**
 393    * This map is used to avoid multiple storage of the same named node: each
 394    * named node is added here when it is written the first time.
 395    */
 396   VrmlData_MapOfNode                            myNamedNodesOut;
 397   /**
 398    * This map allows to resolve multiple reference to any unnamed node. It
 399    * is used during the dummy write (myOutput == 0L). When a node is processed
 400    * the first time it is added to this map, the second time it is automatically
 401    * assigned a name.
 402    */
 403   NCollection_Map<Standard_Address>             myUnnamedNodesOut;
 404   Standard_Integer                              myAutoNameCounter;
 405   friend class VrmlData_Group;
 406   friend class VrmlData_Node;
 407 };
 408
 409 #endif