openscenegraph
ReaderWriter
Go to the documentation of this file.
1/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2006 Robert Osfield
2 *
3 * This library is open source and may be redistributed and/or modified under
4 * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or
5 * (at your option) any later version. The full license is in LICENSE file
6 * included with this distribution, and on the openscenegraph.org website.
7 *
8 * This library is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * OpenSceneGraph Public License for more details.
12*/
13
14#ifndef OSGDB_READERWRITER
15#define OSGDB_READERWRITER 1
16
17#include <osg/Image>
18#include <osg/Shape>
19#include <osg/Node>
20#include <osg/ScriptEngine>
21
22#include <osgDB/AuthenticationMap>
23
24#include <deque>
25#include <list>
26#include <iosfwd>
27
28namespace osgDB {
29
30class Archive;
31
32/** List of directories to search through which searching for files. */
33typedef std::deque<std::string> FilePathList;
34
35// forward declare
36class Options;
37
38/** Pure virtual base class for reading and writing of non native formats. */
39class OSGDB_EXPORT ReaderWriter : public osg::Object
40{
41 public:
42
43
44 ReaderWriter():
45 osg::Object(true) {}
46
47 ReaderWriter(const ReaderWriter& rw,const osg::CopyOp& copyop=osg::CopyOp::SHALLOW_COPY):
48 osg::Object(rw,copyop) {}
49
50 virtual ~ReaderWriter();
51
52 META_Object(osgDB,ReaderWriter);
53
54 typedef std::map<std::string, std::string> FormatDescriptionMap;
55 typedef std::list<std::string> FeatureList;
56
57 /** Return which protocols are supported by ReaderWriter. */
58 virtual const FormatDescriptionMap& supportedProtocols() const { return _supportedProtocols; }
59
60 /** Return which list of file extensions supported by ReaderWriter. */
61 virtual const FormatDescriptionMap& supportedExtensions() const { return _supportedExtensions; }
62
63 /** Return which list of file extensions supported by ReaderWriter. */
64 virtual const FormatDescriptionMap& supportedOptions() const { return _supportedOptions; }
65
66 /** Return true if ReaderWriter accepts specified file extension.*/
67 virtual bool acceptsExtension(const std::string& /*extension*/) const;
68
69 virtual bool acceptsProtocol(const std::string& protocol) const;
70
71 /// Bit mask for setting up which feature types are available for read and/or write
72 enum Features
73 {
74 FEATURE_NONE = 0,
75 FEATURE_READ_OBJECT = 1<<0,
76 FEATURE_READ_IMAGE = 1<<1,
77 FEATURE_READ_HEIGHT_FIELD = 1<<2,
78 FEATURE_READ_NODE = 1<<3,
79 FEATURE_READ_SHADER = 1<<4,
80 FEATURE_WRITE_OBJECT = 1<<5,
81 FEATURE_WRITE_IMAGE = 1<<6,
82 FEATURE_WRITE_HEIGHT_FIELD = 1<<7,
83 FEATURE_WRITE_NODE = 1<<8,
84 FEATURE_WRITE_SHADER = 1<<9,
85 FEATURE_READ_SCRIPT = 1<<10,
86 FEATURE_WRITE_SCRIPT = 1<<11,
87 FEATURE_ALL = FEATURE_READ_OBJECT |
88 FEATURE_READ_IMAGE |
89 FEATURE_READ_HEIGHT_FIELD |
90 FEATURE_READ_NODE |
91 FEATURE_READ_SHADER |
92 FEATURE_READ_SCRIPT |
93 FEATURE_WRITE_OBJECT |
94 FEATURE_WRITE_IMAGE |
95 FEATURE_WRITE_HEIGHT_FIELD |
96 FEATURE_WRITE_NODE |
97 FEATURE_WRITE_SHADER |
98 FEATURE_WRITE_SCRIPT
99 };
100 /** Return available features*/
101 virtual Features supportedFeatures() const;
102
103 /** Return feature as string */
104 static FeatureList featureAsString(Features feature);
105
106
107
108 class OSGDB_EXPORT ReadResult
109 {
110 public:
111
112 enum ReadStatus
113 {
114 NOT_IMPLEMENTED, //!< read*() method not implemented in concrete ReaderWriter.
115 FILE_NOT_HANDLED, //!< File is not appropriate for this file reader, due to some incompatibility, but *not* a read error.
116 FILE_NOT_FOUND, //!< File could not be found or could not be read.
117 ERROR_IN_READING_FILE, //!< File found, loaded, but an error was encountered during processing.
118 FILE_LOADED, //!< File successfully found, loaded, and converted into osg.
119 FILE_LOADED_FROM_CACHE, //!< File found in cache and returned.
120 FILE_REQUESTED, //!< Asynchronous file read has been requested, but returning immediately, keep polling plugin until file read has been completed.
121 INSUFFICIENT_MEMORY_TO_LOAD //!< File found but not loaded because estimated required memory surpasses available memory.
122 };
123
124 ReadResult(ReadStatus status=FILE_NOT_HANDLED):_status(status) {}
125 ReadResult(const std::string& m):_status(ERROR_IN_READING_FILE),_message(m) {}
126
127 ReadResult(osg::Object* obj, ReadStatus status=FILE_LOADED):_status(status),_object(obj) {}
128
129 template<class T>
130 ReadResult(const osg::ref_ptr<T>& obj, ReadStatus status=FILE_LOADED):_status(status),_object(obj.get()) {}
131
132 ReadResult(const ReadResult& rr):_status(rr._status),_message(rr._message),_object(rr._object) {}
133 ReadResult& operator = (const ReadResult& rr) { if (this==&rr) return *this; _status=rr._status; _message=rr._message;_object=rr._object; return *this; }
134
135 bool operator < (const ReadResult& rhs) const { return _status < rhs._status; }
136
137 osg::Object* getObject();
138 osg::Image* getImage();
139 osg::HeightField* getHeightField();
140 osg::Node* getNode();
141 osgDB::Archive* getArchive();
142 osg::Shader* getShader();
143 osg::Script* getScript();
144
145 bool validObject() { return _object.valid(); }
146 bool validImage() { return getImage()!=0; }
147 bool validHeightField() { return getHeightField()!=0; }
148 bool validNode() { return getNode()!=0; }
149 bool validArchive() { return getArchive()!=0; }
150 bool validShader() { return getShader()!=0; }
151 bool validScript() { return getScript()!=0; }
152
153 osg::Object* takeObject();
154 osg::Image* takeImage();
155 osg::HeightField* takeHeightField();
156 osg::Node* takeNode();
157 osgDB::Archive* takeArchive();
158 osg::Shader* takeShader();
159 osg::Script* takeScript();
160
161 std::string& message() { return _message; }
162 const std::string& message() const { return _message; }
163
164 /// report the ReadResult's status, and message (if any). Useful for reporting of errors to users.
165 std::string statusMessage() const;
166
167 ReadStatus status() const { return _status; }
168 bool success() const { return _status==FILE_LOADED || _status==FILE_LOADED_FROM_CACHE ; }
169 bool loadedFromCache() const { return _status==FILE_LOADED_FROM_CACHE; }
170 bool error() const { return _status==ERROR_IN_READING_FILE; }
171 bool notHandled() const { return _status==FILE_NOT_HANDLED || _status==NOT_IMPLEMENTED; }
172 bool notFound() const { return _status==FILE_NOT_FOUND; }
173 bool notEnoughMemory() const { return _status==INSUFFICIENT_MEMORY_TO_LOAD; }
174
175 protected:
176
177 ReadStatus _status;
178 std::string _message;
179 osg::ref_ptr<osg::Object> _object;
180
181 };
182
183 class WriteResult
184 {
185 public:
186
187 enum WriteStatus
188 {
189 NOT_IMPLEMENTED, //!< write*() method not implemented in concrete ReaderWriter.
190 FILE_NOT_HANDLED,
191 ERROR_IN_WRITING_FILE,
192 FILE_SAVED
193 };
194
195 WriteResult(WriteStatus status=FILE_NOT_HANDLED):_status(status) {}
196 WriteResult(const std::string& m):_status(ERROR_IN_WRITING_FILE),_message(m) {}
197
198 WriteResult(const WriteResult& rr):_status(rr._status),_message(rr._message) {}
199 WriteResult& operator = (const WriteResult& rr) { if (this==&rr) return *this; _status=rr._status; _message=rr._message; return *this; }
200
201 bool operator < (const WriteResult& rhs) const { return _status < rhs._status; }
202
203 std::string& message() { return _message; }
204 const std::string& message() const { return _message; }
205
206 /// Report the WriteResult's status, and message (if any). Useful for reporting of errors to users.
207 std::string statusMessage() const;
208
209 WriteStatus status() const { return _status; }
210 bool success() const { return _status==FILE_SAVED; }
211 bool error() const { return _status==ERROR_IN_WRITING_FILE; }
212 bool notHandled() const { return _status==FILE_NOT_HANDLED || _status==NOT_IMPLEMENTED; }
213
214 protected:
215
216 WriteStatus _status;
217 std::string _message;
218 };
219
220 enum ArchiveStatus
221 {
222 READ,
223 WRITE,
224 CREATE
225 };
226
227 typedef osgDB::Options Options;
228
229 /** Determine if a file exists, normally the default implementation will be appropriate for local file access
230 * but with plugins like the libcurl based one it will return true if the file is accessible at the server. */
231 virtual bool fileExists(const std::string& filename, const Options* options) const;
232
233 /** Open an archive for reading, writing, or to create an empty archive for writing to.*/
234 virtual ReadResult openArchive(const std::string& /*fileName*/,ArchiveStatus, unsigned int =4096, const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); }
235
236 /** Open an archive for reading.*/
237 virtual ReadResult openArchive(std::istream& /*fin*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); }
238
239 virtual ReadResult readObject(const std::string& /*fileName*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); }
240 virtual ReadResult readImage(const std::string& /*fileName*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); }
241 virtual ReadResult readHeightField(const std::string& /*fileName*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); }
242 virtual ReadResult readNode(const std::string& /*fileName*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); }
243 virtual ReadResult readShader(const std::string& /*fileName*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); }
244 virtual ReadResult readScript(const std::string& /*fileName*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); }
245
246 virtual WriteResult writeObject(const osg::Object& /*obj*/,const std::string& /*fileName*/,const Options* =NULL) const {return WriteResult(WriteResult::NOT_IMPLEMENTED); }
247 virtual WriteResult writeImage(const osg::Image& /*image*/,const std::string& /*fileName*/,const Options* =NULL) const {return WriteResult(WriteResult::NOT_IMPLEMENTED); }
248 virtual WriteResult writeHeightField(const osg::HeightField& /*heightField*/,const std::string& /*fileName*/,const Options* =NULL) const {return WriteResult(WriteResult::NOT_IMPLEMENTED); }
249 virtual WriteResult writeNode(const osg::Node& /*node*/,const std::string& /*fileName*/,const Options* =NULL) const { return WriteResult(WriteResult::NOT_IMPLEMENTED); }
250 virtual WriteResult writeShader(const osg::Shader& /*shader*/,const std::string& /*fileName*/,const Options* =NULL) const {return WriteResult(WriteResult::NOT_IMPLEMENTED); }
251 virtual WriteResult writeScript(const osg::Script& /*script*/,const std::string& /*fileName*/,const Options* =NULL) const {return WriteResult(WriteResult::NOT_IMPLEMENTED); }
252
253 virtual ReadResult readObject(std::istream& /*fin*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); }
254 virtual ReadResult readImage(std::istream& /*fin*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); }
255 virtual ReadResult readHeightField(std::istream& /*fin*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); }
256 virtual ReadResult readNode(std::istream& /*fin*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); }
257 virtual ReadResult readShader(std::istream& /*fin*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); }
258 virtual ReadResult readScript(std::istream& /*fin*/,const Options* =NULL) const { return ReadResult(ReadResult::NOT_IMPLEMENTED); }
259
260 virtual WriteResult writeObject(const osg::Object& /*obj*/,std::ostream& /*fout*/,const Options* =NULL) const { return WriteResult(WriteResult::NOT_IMPLEMENTED); }
261 virtual WriteResult writeImage(const osg::Image& /*image*/,std::ostream& /*fout*/,const Options* =NULL) const { return WriteResult(WriteResult::NOT_IMPLEMENTED); }
262 virtual WriteResult writeHeightField(const osg::HeightField& /*heightField*/,std::ostream& /*fout*/,const Options* =NULL) const { return WriteResult(WriteResult::NOT_IMPLEMENTED); }
263 virtual WriteResult writeNode(const osg::Node& /*node*/,std::ostream& /*fout*/,const Options* =NULL) const { return WriteResult(WriteResult::NOT_IMPLEMENTED); }
264 virtual WriteResult writeShader(const osg::Shader& /*shader*/,std::ostream& /*fout*/,const Options* =NULL) const { return WriteResult(WriteResult::NOT_IMPLEMENTED); }
265 virtual WriteResult writeScript(const osg::Script& /*script*/,std::ostream& /*fout*/,const Options* =NULL) const { return WriteResult(WriteResult::NOT_IMPLEMENTED); }
266
267 /** Specify fmt string as a supported protocol.
268 * Please note, this method should usually only be used internally by subclasses of ReaderWriter, Only in special cases
269 * will a ReaderWriter implementation be able to handle a protocol format that it wasn't originally designed for.
270 * To know whether it's safe to inject a new protocol format into an existing ReaderWriter you will need to review
271 * the source code and dependencies of that ReaderWriter. */
272 void supportsProtocol(const std::string& fmt, const std::string& description);
273
274 /** Specify ext string as a supported file extension.
275 * Please note, this method should usually only be used internally by subclasses of ReaderWriter. Only in special cases
276 * will a ReaderWriter implementation be able to handle a file extension that it wasn't originally designed for.
277 * To know whether it's safe to inject a new file extension into an existing ReaderWriter you will need to review the
278 * the source code and dependencies of that ReaderWriter. */
279 void supportsExtension(const std::string& ext, const std::string& description);
280
281 /** Specify option string as a supported option string.
282 * Please note, this should usually only be used internally by subclasses of ReaderWriter. */
283 void supportsOption(const std::string& opt, const std::string& description);
284
285 protected:
286
287 FormatDescriptionMap _supportedProtocols;
288 FormatDescriptionMap _supportedExtensions;
289 FormatDescriptionMap _supportedOptions;
290};
291
292}
293
294#endif // OSGDB_READERWRITER