Doc/to_port/FileIO.dox

   1 #include <OSGConfig.h>
   2
   3 using namespace OSG;
   4
   5 /*! \defgroup GrpSystemFileIO File Input/Output
   6     \ingroup GrpSystem
   7
   8 Reader/Writer
   9
  10 See \ref PageSystemFileIO for details.
  11 */
  12
  13 /*! \page PageSystemFileIO File Input/Output
  14
  15 \latexonly Starter:NewChapter \endlatexonly
  16
  17 As OpenSG user/developer you can always instantiate all your nodes, cores or
  18 whatever objects you need one by one in your application code.
  19
  20 In addition OpenSG also provides - as most scene-graph libraries - a set of
  21 loaders, which create a scene tree or image from a given file. The system
  22 creates singleton Handlers for both types (SceneFileHandler and
  23 ImageFileHandler), which handle all abstract requests. The concrete loaders
  24 are coded in mime/file type handlers (e.g.
  25 OSGTIFImageFileType.h/OSGTIFImageFileType.cpp) and are automatically
  26 registered.
  27
  28 The system architecture is designed to handle built-in types and to fetch
  29 loaders for a specific type on request. In the current version (1.0) only
  30 built-in types are provided since the meta interfaces may not be final yet.
  31 However the 1.0 version comes with a sufficient set of built-in loaders and
  32 you can always extend the library to handle you own file format.
  33
  34 \section PageSystemFileIOUsage Usage
  35
  36 You can always use a specific loader directly, but in most cases you would ask
  37 the Handler (e.g. SceneFileHandler) to load a file independent of the file
  38 type. There is always just one handler (it is a singleton object) you can
  39 access the object using the static the() method (e.g.
  40 osg::SceneFileType::the()). The Handler knows all the valid suffixes for every
  41 mime/file type and can pick the correct loader automatically.
  42
  43 If you would like to get a loader for a specific type or suffix you can just
  44 ask the handler to find it (e.g. SceneFileHandler::the().getFileType("wrl")).
  45
  46 \subsection PageSystemFileIOUsageScene Scene
  47
  48 The Scene Handler provides two interfaces to load a scene: read (returns a
  49 single root node or NullFC on failure) or readTopNodes (does not create an
  50 extra root but returns all top nodes ).
  51
  52 Just use the Handler to find and use the correct type for the given suffix:
  53 osg::NodePtr rootPtr =
  54 osg::SceneFileTypeSceneFileHandler::the().read("test.wrl") for example would
  55 pick the VRML loader (suffix is "wrl"), parse the file and return the result.
  56
  57 \subsection PageSystemFileIOUsageImage Image
  58
  59 The image loader works more or less the same way as the scene loader. Let the
  60 singleton handler pick the mime type and just check the return value:
  61 osg::ImageFileHandler::the().read("test.tif") for example would pick the tif
  62 loader (suffix "tif" ), start loading the file, and return the new Image or
  63 Null.
  64
  65 \ext
  66
  67 \section PageSystemFileIOWrite Write our own
  68
  69 For every new mime/file you have to write a new "Type" class (e.g.
  70 FooImageType.h/FooImageType.cpp). Every Type is handled as a singleton object
  71 and must provide a the() method to access the static instance. The class must
  72 be derived from the base Type (e.g. ImageFileType) to be registered. You don't
  73 have to register the new type in any extra class. Just included it in the
  74 OpenSG source tree and it should work with the Handler.
  75
  76 \subsection PageSystemFileIOWriteScene Scene
  77
  78 Since scene loaders are usually more complex and require sometimes some extra
  79 library they have extra directories for their sources (e.g.
  80 OpenSG/Loader/WRL). To write your own scene handler perform the following
  81 steps:
  82
  83 \li Create a new directory for your mime type (e.g. OpenSG/Loader/FOO)
  84
  85 \li Copy the code from a simple loader (e.g. Loader/RAW)
  86
  87 \li Change the file file/class name to match your type.
  88
  89 \li Change the _suffixA values in the *.cpp file (e.g {"foo"} ), you can
  90 includes as many valid suffixes as you want
  91
  92 \li Write the read() methods to load your type
  93
  94 \li configure/make opensg libs
  95
  96 \subsection PageSystemFileIOWriteImage Image
  97
  98 Image loaders are usually not too complex. They usually just use some external
  99 library (e.g. tifflib) to load the image data. Since the extra lib is usually
 100 not included in the opensg source tree we do not store the code in an extra,
 101 mime type specific directory. They are all stored in OpenSG/Image.
 102
 103 To write you own image loader perform the following steps:
 104
 105 \li Copy the code from a simple loader (e.g. Image/PNMImageFileType.*)
 106
 107 \li Change the file file/class name to match you type.
 108
 109 \li Change the _suffixA values in the *.cpp file (e.g {"foo"} ), you can
 110 includes as many valid suffixes as you want
 111
 112 \li Change the getMimeType() method in *.h to return the new mime type.
 113
 114 \li Write the read()/write() methods to load/write your type
 115
 116 \li configure/make opensg libs
 117
 118
 119 */