1/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2006 Robert Osfield
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.
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.
15#define OSGDB_READFILE 1
21#include <osg/ArgumentParser>
23#include <osgDB/Export>
24#include <osgDB/Registry>
29/** Read an osg::Object from file.
30 * Return an assigned osg::ref_ptr on success,
31 * return an osg::ref_ptr with a NULL pointer assigned to it on failure.
32 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
33 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
34 * for the filename extension, and this plugin then handles the request
35 * to read the specified file.*/
36extern OSGDB_EXPORT osg::ref_ptr<osg::Object> readRefObjectFile(const std::string& filename,const Options* options);
38/** Read an osg::Object from file.
39 * Return an assigned osg::ref_ptr on success,
40 * return an osg::ref_ptr with a NULL pointer assigned to it on failure.
41 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
42 * for the filename extension, and this plugin then handles the request
43 * to read the specified file.*/
44inline osg::ref_ptr<osg::Object> readRefObjectFile(const std::string& filename)
46 return readRefObjectFile(filename, Registry::instance()->getOptions());
50inline osg::ref_ptr<T> readRefFile(const std::string& filename, const Options* options)
52 osg::ref_ptr<osg::Object> object = readRefObjectFile(filename, options);
53 osg::ref_ptr<T> t = dynamic_cast<T*>(object.get());
58inline osg::ref_ptr<T> readRefFile(const std::string& filename)
60 return readRefFile<T>(filename, Registry::instance()->getOptions());
64/** Read an osg::Image from file.
65 * Return an assigned osg::ref_ptr on success,
66 * return an osg::ref_ptr with a NULL pointer assigned to it on failure.
67 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
68 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
69 * for the filename extension, and this plugin then handles the request
70 * to read the specified file.*/
71extern OSGDB_EXPORT osg::ref_ptr<osg::Image> readRefImageFile(const std::string& filename,const Options* options);
73/** Read an osg::Image from file.
74 * Return an assigned osg::ref_ptr on success,
75 * return an osg::ref_ptr with a NULL pointer assigned to it on failure.
76 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
77 * for the filename extension, and this plugin then handles the request
78 * to read the specified file.*/
79inline osg::ref_ptr<osg::Image> readRefImageFile(const std::string& filename)
81 return readRefImageFile(filename,Registry::instance()->getOptions());
84/** Read an osg::HeightField from file.
85 * Return an assigned osg::ref_ptr on success,
86 * return an osg::ref_ptr with a NULL pointer assigned to it on failure.
87 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
88 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
89 * for the filename extension, and this plugin then handles the request
90 * to read the specified file.*/
91extern OSGDB_EXPORT osg::ref_ptr<osg::HeightField> readRefHeightFieldFile(const std::string& filename,const Options* options);
93/** Read an osg::HeightField from file.
94 * Return an assigned osg::ref_ptr on success,
95 * return an osg::ref_ptr with a NULL pointer assigned to it on failure.
96 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
97 * for the filename extension, and this plugin then handles the request
98 * to read the specified file.*/
99inline osg::ref_ptr<osg::HeightField> readRefHeightFieldFile(const std::string& filename)
101 return readRefHeightFieldFile(filename,Registry::instance()->getOptions());
104/** Read an osg::Node from file.
105 * Return an assigned osg::ref_ptr on success,
106 * return an osg::ref_ptr with a NULL pointer assigned to it on failure.
107 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
108 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
109 * for the filename extension, and this plugin then handles the request
110 * to read the specified file.*/
111extern OSGDB_EXPORT osg::ref_ptr<osg::Node> readRefNodeFile(const std::string& filename,const Options* options);
113/** Read an osg::Node from file.
114 * Return an assigned osg::ref_ptr on success,
115 * return an osg::ref_ptr with a NULL pointer assigned to it on failure.
116 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
117 * for the filename extension, and this plugin then handles the request
118 * to read the specified file.*/
119inline osg::ref_ptr<osg::Node> readRefNodeFile(const std::string& filename)
121 return readRefNodeFile(filename,Registry::instance()->getOptions());
124/** Read an osg::Node subgraph from files, creating a osg::Group to contain the nodes if more
125 * than one subgraph has been loaded.
126 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
127 * Does NOT ignore strings beginning with a dash '-' character. */
128extern OSGDB_EXPORT osg::ref_ptr<osg::Node> readRefNodeFiles(std::vector<std::string>& fileList,const Options* options);
130/** Read an osg::Node subgraph from files, creating a osg::Group to contain the nodes if more
131 * than one subgraph has been loaded.*/
132inline osg::ref_ptr<osg::Node> readRefNodeFiles(std::vector<std::string>& fileList)
134 return readRefNodeFiles(fileList, Registry::instance()->getOptions());
138/** Read an osg::Node subgraph from files, creating a osg::Group to contain the nodes if more
139 * than one subgraph has been loaded.
140 * Use the Options object to control cache operations and file search paths in osgDB::Registry.*/
141extern OSGDB_EXPORT osg::ref_ptr<osg::Node> readRefNodeFiles(osg::ArgumentParser& parser,const Options* options);
143/** Read an osg::Node subgraph from files, creating a osg::Group to contain the nodes if more
144 * than one subgraph has been loaded.*/
145inline osg::ref_ptr<osg::Node> readRefNodeFiles(osg::ArgumentParser& parser)
147 return readRefNodeFiles(parser,Registry::instance()->getOptions());
150/** Read an osg::Shader from file.
151 * Return an assigned osg::ref_ptr on success,
152 * return an osg::ref_ptr with a NULL pointer assigned to it on failure.
153 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
154 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
155 * for the filename extension, and this plugin then handles the request
156 * to read the specified file.*/
157extern OSGDB_EXPORT osg::ref_ptr<osg::Shader> readRefShaderFile(const std::string& filename,const Options* options);
159/** Read an osg::Shader from file.
160 * Return an assigned osg::ref_ptr on success,
161 * return an osg::ref_ptr with a NULL pointer assigned to it on failure.
162 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
163 * for the filename extension, and this plugin then handles the request
164 * to read the specified file.*/
165inline osg::ref_ptr<osg::Shader> readRefShaderFile(const std::string& filename)
167 return readRefShaderFile(filename, Registry::instance()->getOptions());
170/** Read an osg::Shader from file and set to specified shader type.
171 * Return valid osg::Shader on success,
172 * return NULL on failure.
173 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
174 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
175 * for the filename extension, and this plugin then handles the request
176 * to read the specified file.*/
177inline osg::ref_ptr<osg::Shader> readRefShaderFile(osg::Shader::Type type, const std::string& filename, const Options* options)
179 osg::ref_ptr<osg::Shader> shader = readRefShaderFile(filename, options);
180 if (shader.valid() && type != osg::Shader::UNDEFINED) shader->setType(type);
184/** Read an osg::Shader from file and set to specified shader type
185 * Return valid osg::Shader on success,
186 * return NULL on failure.
187 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
188 * for the filename extension, and this plugin then handles the request
189 * to read the specified file.*/
190inline osg::ref_ptr<osg::Shader> readRefShaderFile(osg::Shader::Type type, const std::string& filename)
192 return readRefShaderFile(type, filename, Registry::instance()->getOptions());
195/** Read an osg::Shader from file and set to specified shader type, if a shader isn't loaded fallback to specific shader source.
196 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
197 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
198 * for the filename extension, and this plugin then handles the request
199 * to read the specified file.*/
200extern OSGDB_EXPORT osg::ref_ptr<osg::Shader> readRefShaderFileWithFallback(osg::Shader::Type type, const std::string& filename, const Options* options, const char* fallback);
202/** Read an osg::Shader from file and set to specified shader type, if a shader isn't loaded fallback to specific shader source.
203 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
204 * for the filename extension, and this plugin then handles the request
205 * to read the specified file.*/
206inline osg::ref_ptr<osg::Shader> readRefShaderFileWithFallback(osg::Shader::Type type, const std::string& filename, const char* fallback)
208 return osgDB::readRefShaderFileWithFallback(type, filename, Registry::instance()->getOptions(), fallback);
211/** Read an osg::Script from file.
212 * Return an assigned osg::ref_ptr on success,
213 * return an osg::ref_ptr with a NULL pointer assigned to it on failure.
214 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
215 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
216 * for the filename extension, and this plugin then handles the request
217 * to read the specified file.*/
218extern OSGDB_EXPORT osg::ref_ptr<osg::Script> readRefScriptFile(const std::string& filename,const Options* options);
220/** Read an osg::Script from file.
221 * Return an assigned osg::ref_ptr on success,
222 * return an osg::ref_ptr with a NULL pointer assigned to it on failure.
223 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
224 * for the filename extension, and this plugin then handles the request
225 * to read the specified file.*/
226inline osg::ref_ptr<osg::Script> readRefScriptFile(const std::string& filename)
228 return readRefScriptFile(filename,Registry::instance()->getOptions());
231#ifdef OSG_PROVIDE_READFILE
232/** Read an osg::Object from file.
233 * Return valid osg::Object on success,
234 * return NULL on failure.
235 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
236 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
237 * for the filename extension, and this plugin then handles the request
238 * to read the specified file.*/
239extern OSGDB_EXPORT osg::Object* readObjectFile(const std::string& filename,const Options* options);
241/** Read an osg::Object from file.
242 * Return valid osg::Object on success,
243 * return NULL on failure.
244 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
245 * for the filename extension, and this plugin then handles the request
246 * to read the specified file.*/
247inline osg::Object* readObjectFile(const std::string& filename)
249 return readObjectFile(filename, Registry::instance()->getOptions());
253inline T* readFile(const std::string& filename, const Options* options)
255 osg::ref_ptr<osg::Object> object = readRefObjectFile(filename, options);
256 osg::ref_ptr<T> t = dynamic_cast<T*>(object.get());
262inline T* readFile(const std::string& filename)
264 return readFile<T>(filename, Registry::instance()->getOptions());
268/** Read an osg::Image from file.
269 * Return valid osg::Image on success,
270 * return NULL on failure.
271 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
272 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
273 * for the filename extension, and this plugin then handles the request
274 * to read the specified file.*/
275extern OSGDB_EXPORT osg::Image* readImageFile(const std::string& filename,const Options* options);
277/** Read an osg::Image from file.
278 * Return valid osg::Image on success,
279 * return NULL on failure.
280 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
281 * for the filename extension, and this plugin then handles the request
282 * to read the specified file.*/
283inline osg::Image* readImageFile(const std::string& filename)
285 return readImageFile(filename,Registry::instance()->getOptions());
288/** Read an osg::HeightField from file.
289 * Return valid osg::HeightField on success,
290 * return NULL on failure.
291 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
292 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
293 * for the filename extension, and this plugin then handles the request
294 * to read the specified file.*/
295extern OSGDB_EXPORT osg::HeightField* readHeightFieldFile(const std::string& filename,const Options* options);
297/** Read an osg::HeightField from file.
298 * Return valid osg::HeightField on success,
299 * return NULL on failure.
300 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
301 * for the filename extension, and this plugin then handles the request
302 * to read the specified file.*/
303inline osg::HeightField* readHeightFieldFile(const std::string& filename)
305 return readHeightFieldFile(filename,Registry::instance()->getOptions());
308/** Read an osg::Node from file.
309 * Return valid osg::Node on success,
310 * return NULL on failure.
311 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
312 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
313 * for the filename extension, and this plugin then handles the request
314 * to read the specified file.*/
315extern OSGDB_EXPORT osg::Node* readNodeFile(const std::string& filename,const Options* options);
317/** Read an osg::Node from file.
318 * Return valid osg::Node on success,
319 * return NULL on failure.
320 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
321 * for the filename extension, and this plugin then handles the request
322 * to read the specified file.*/
323inline osg::Node* readNodeFile(const std::string& filename)
325 return readNodeFile(filename,Registry::instance()->getOptions());
329/** Read an osg::Node subgraph from files, creating a osg::Group to contain the nodes if more
330 * than one subgraph has been loaded.
331 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
332 * Does NOT ignore strings beginning with a dash '-' character. */
333extern OSGDB_EXPORT osg::Node* readNodeFiles(std::vector<std::string>& fileList,const Options* options);
335/** Read an osg::Node subgraph from files, creating a osg::Group to contain the nodes if more
336 * than one subgraph has been loaded.*/
337inline osg::Node* readNodeFiles(std::vector<std::string>& fileList)
339 return readNodeFiles(fileList,Registry::instance()->getOptions());
343/** Read an osg::Node subgraph from files, creating a osg::Group to contain the nodes if more
344 * than one subgraph has been loaded.
345 * Use the Options object to control cache operations and file search paths in osgDB::Registry.*/
346extern OSGDB_EXPORT osg::Node* readNodeFiles(osg::ArgumentParser& parser,const Options* options);
348/** Read an osg::Node subgraph from files, creating a osg::Group to contain the nodes if more
349 * than one subgraph has been loaded.*/
350inline osg::Node* readNodeFiles(osg::ArgumentParser& parser)
352 return readNodeFiles(parser,Registry::instance()->getOptions());
355/** Read an osg::Shader from file.
356 * Return valid osg::Shader on success,
357 * return NULL on failure.
358 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
359 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
360 * for the filename extension, and this plugin then handles the request
361 * to read the specified file.*/
362extern OSGDB_EXPORT osg::Shader* readShaderFile(const std::string& filename,const Options* options);
364/** Read an osg::Shader from file.
365 * Return valid osg::Shader on success,
366 * return NULL on failure.
367 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
368 * for the filename extension, and this plugin then handles the request
369 * to read the specified file.*/
370inline osg::Shader* readShaderFile(const std::string& filename)
372 return readShaderFile(filename,Registry::instance()->getOptions());
375/** Read an osg::Shader from file and set to specified shader type.
376 * Return valid osg::Shader on success,
377 * return NULL on failure.
378 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
379 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
380 * for the filename extension, and this plugin then handles the request
381 * to read the specified file.*/
382inline osg::Shader* readShaderFile(osg::Shader::Type type, const std::string& filename,const Options* options)
384 osg::Shader* shader = readShaderFile(filename, options);
385 if (shader && type != osg::Shader::UNDEFINED) shader->setType(type);
389/** Read an osg::Shader from file and set to specified shader type
390 * Return valid osg::Shader on success,
391 * return NULL on failure.
392 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
393 * for the filename extension, and this plugin then handles the request
394 * to read the specified file.*/
395inline osg::Shader* readShaderFile(osg::Shader::Type type, const std::string& filename)
397 return readShaderFile(type, filename,Registry::instance()->getOptions());
401/** Read an osg::Shader from file and set to specified shader type, if a shader isn't loaded fallback to specific shader source.
402 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
403 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
404 * for the filename extension, and this plugin then handles the request
405 * to read the specified file.*/
406inline osg::Shader* readShaderFileWithFallback(osg::Shader::Type type, const std::string& filename, const Options* options, const char* fallback)
408 osg::Shader* shader = readShaderFile(filename, options);
409 if (shader && type != osg::Shader::UNDEFINED) shader->setType(type);
410 if (!shader) shader = new osg::Shader(type, fallback);
414/** Read an osg::Shader from file and set to specified shader type, if a shader isn't loaded fallback to specific shader source.
415 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
416 * for the filename extension, and this plugin then handles the request
417 * to read the specified file.*/
418inline osg::Shader* readShaderFileWithFallback(osg::Shader::Type type, const std::string& filename, const char* fallback)
420 return osgDB::readShaderFileWithFallback(type, filename, Registry::instance()->getOptions(), fallback);
423/** Read an osg::Script from file.
424 * Return valid osg::Script on success,
425 * return NULL on failure.
426 * Use the Options object to control cache operations and file search paths in osgDB::Registry.
427 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
428 * for the filename extension, and this plugin then handles the request
429 * to read the specified file.*/
430extern OSGDB_EXPORT osg::Script* readScriptFile(const std::string& filename,const Options* options);
432/** Read an osg::Script from file.
433 * Return valid osg::Script on success,
434 * return NULL on failure.
435 * The osgDB::Registry is used to load the appropriate ReaderWriter plugin
436 * for the filename extension, and this plugin then handles the request
437 * to read the specified file.*/
438inline osg::Script* readScriptFile(const std::string& filename)
440 return readScriptFile(filename,Registry::instance()->getOptions());