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_OPTIONS
15#define OSGDB_OPTIONS 1
16
17#include <osgDB/Callbacks>
18#include <osgDB/ObjectCache>
19#include <osg/ObserverNodePath>
20
21#include <deque>
22#include <list>
23#include <iosfwd>
24
25namespace osgDB {
26
27
28/** Options base class used for passing options into plugins to control their operation.*/
29class OSGDB_EXPORT Options : public osg::Object
30{
31    public:
32
33        /// bit mask for setting up which object types get cached by readObject/Image/HeightField/Node(filename) calls
34        enum CacheHintOptions
35        {   /// do not cache objects of any type
36            CACHE_NONE          = 0,
37
38            /// cache nodes loaded via readNode(filename)
39            CACHE_NODES         = 1<<0,
40
41            /// cache images loaded via readImage(filename)
42            CACHE_IMAGES        = 1<<1,
43
44            /// cache heightfield loaded via readHeightField(filename)
45            CACHE_HEIGHTFIELDS  = 1<<2,
46
47            /// cache heightfield loaded via readHeightField(filename)
48            CACHE_ARCHIVES      = 1<<3,
49
50            /// cache objects loaded via readObject(filename)
51            CACHE_OBJECTS       = 1<<4,
52
53            /// cache shaders loaded via readShader(filename)
54            CACHE_SHADERS       = 1<<5,
55
56            /// cache on all read*(filename) calls
57            CACHE_ALL           = CACHE_NODES |
58                                    CACHE_IMAGES |
59                                    CACHE_HEIGHTFIELDS |
60                                    CACHE_ARCHIVES |
61                                    CACHE_OBJECTS |
62                                    CACHE_SHADERS
63        };
64
65        /// Bit mask for which geometry attributes should be imported with double precision where source data is held in double precision
66        /// This is useful for data that will be pre-processed before rendering.
67        /// In general the geometry should be converted to floating point before rendering to ensure good performance.
68        enum PrecisionHint
69        {
70            FLOAT_PRECISION_ALL              = 0,
71
72            DOUBLE_PRECISION_VERTEX          = 1<<0,
73            DOUBLE_PRECISION_NORMAL          = 1<<1,
74            DOUBLE_PRECISION_COLOR           = 1<<2,
75            DOUBLE_PRECISION_SECONDARY_COLOR = 1<<3,
76            DOUBLE_PRECISION_FOG_COORD       = 1<<4,
77            DOUBLE_PRECISION_TEX_COORD       = 1<<5,
78            DOUBLE_PRECISION_VERTEX_ATTRIB   = 1<<6,
79
80            DOUBLE_PRECISION_ALL = DOUBLE_PRECISION_VERTEX |
81                                   DOUBLE_PRECISION_NORMAL |
82                                   DOUBLE_PRECISION_COLOR |
83                                   DOUBLE_PRECISION_SECONDARY_COLOR |
84                                   DOUBLE_PRECISION_FOG_COORD |
85                                   DOUBLE_PRECISION_TEX_COORD |
86                                   DOUBLE_PRECISION_VERTEX_ATTRIB
87        };
88
89        /// range of options of whether to build kdtrees automatically on loading
90        enum BuildKdTreesHint
91        {
92            NO_PREFERENCE,
93            DO_NOT_BUILD_KDTREES,
94            BUILD_KDTREES
95        };
96
97
98        Options();
99
100        Options(const std::string& str);
101
102        Options(const Options& options,const osg::CopyOp& copyop=osg::CopyOp::SHALLOW_COPY);
103
104        META_Object(osgDB,Options);
105
106        Options* cloneOptions(const osg::CopyOp& copyop=osg::CopyOp::SHALLOW_COPY) const { return static_cast<Options*>(clone(copyop)); }
107
108        /** Set the general Options string.*/
109        void setOptionString(const std::string& str) { _str = str; parsePluginStringData(str); }
110
111        /** Get the general Options string.*/
112        const std::string& getOptionString() const { return _str; }
113
114        /** Set the database path to use a hint of where to look when loading models.*/
115        void setDatabasePath(const std::string& str) { _databasePaths.clear();  _databasePaths.push_back(str); }
116
117        /** Get the database path which is used a hint of where to look when loading models.*/
118        FilePathList& getDatabasePathList() { return _databasePaths; }
119
120        /** Get the const database path which is used a hint of where to look when loading models.*/
121        const FilePathList& getDatabasePathList() const { return _databasePaths; }
122
123
124        /** Set whether the Registry::ObjectCache should be used by default.*/
125        void setObjectCacheHint(CacheHintOptions useObjectCache) { _objectCacheHint = useObjectCache; }
126
127        /** Get whether the Registry::ObjectCache should be used by default.*/
128        CacheHintOptions getObjectCacheHint() const { return _objectCacheHint; }
129
130        /** Set the ObjectCache that is used to cache previously loaded data.*/
131        void setObjectCache(ObjectCache* objectCache) { _objectCache = objectCache; }
132
133        /** Get the ObjectCache that is used to cache previously loaded data.*/
134        ObjectCache* getObjectCache() const { return _objectCache.get(); }
135
136
137        /** Set which geometry attributes plugins should import at double precision. */
138        void setPrecisionHint(PrecisionHint hint) { _precisionHint = hint; }
139
140        /** Get which geometry attributes plugins should import at double precision. */
141        PrecisionHint getPrecisionHint() const { return _precisionHint; }
142
143        /** Set whether the KdTrees should be built for geometry in the loader model. */
144        void setBuildKdTreesHint(BuildKdTreesHint hint) { _buildKdTreesHint = hint; }
145
146        /** Get whether the KdTrees should be built for geometry in the loader model. */
147        BuildKdTreesHint getBuildKdTreesHint() const { return _buildKdTreesHint; }
148
149
150        /** Set the password map to be used by plugins when access files from secure locations.*/
151        void setAuthenticationMap(AuthenticationMap* authenticationMap) { _authenticationMap = authenticationMap; }
152
153        /** Get the password map to be used by plugins when access files from secure locations.*/
154        const AuthenticationMap* getAuthenticationMap() const { return _authenticationMap.get(); }
155
156
157        /** Sets a plugindata value PluginData with a string */
158        void setPluginData(const std::string& s, void* v) const { _pluginData[s] = v; }
159
160        /** Get a value from the PluginData */
161        void* getPluginData(const std::string& s) { return _pluginData[s]; }
162
163        /** Get a value from the PluginData */
164        const void* getPluginData(const std::string& s) const
165        {
166            PluginDataMap::const_iterator itr = _pluginData.find(s);
167            return (itr == _pluginData.end()) ? 0 : itr->second;
168        }
169
170        /** Remove a value from the PluginData */
171        void removePluginData(const std::string& s) const { _pluginData.erase(s); }
172
173        /** Get number of PluginData values */
174        unsigned int getNumPluginData() const { return static_cast<unsigned int>(_pluginData.size()); }
175
176
177        /** Sets a plugindata value PluginData with a string */
178        void setPluginStringData(const std::string& s, const std::string& v) const { _pluginStringData[s] = v; }
179
180        /** Get a string from the PluginStrData */
181        std::string& getPluginStringData(const std::string& s) { return _pluginStringData[s]; }
182
183        /** Get a value from the PluginData */
184        const std::string getPluginStringData(const std::string& s) const
185        {
186            PluginStringDataMap::const_iterator itr = _pluginStringData.find(s);
187            return (itr == _pluginStringData.end()) ? std::string("") : itr->second;
188        }
189
190        /** Remove a value from the PluginData */
191        void removePluginStringData(const std::string& s) const { _pluginStringData.erase(s); }
192
193        /** Get number of PluginStrData values */
194        unsigned int getNumPluginStringData() const { return static_cast<unsigned int>(_pluginStringData.size()); }
195
196        /** Parse string into plugin string data. This will be automatically done in Options(const std::string&) */
197        void parsePluginStringData(const std::string& str, char separator1=' ', char separator2='=');
198
199
200        /** Set the find callback to use in place of the default findFile calls.*/
201        void setFindFileCallback( FindFileCallback* cb) { _findFileCallback = cb; }
202
203        /** Get the const findFile callback.*/
204        FindFileCallback* getFindFileCallback() const { return _findFileCallback.get(); }
205
206
207        /** Set the read callback to use in place of the default readFile calls.*/
208        void setReadFileCallback( ReadFileCallback* cb) { _readFileCallback = cb; }
209
210        /** Get the const readFile callback.*/
211        ReadFileCallback* getReadFileCallback() const { return _readFileCallback.get(); }
212
213
214        /** Set the callback to use in place of the default writeFile calls.*/
215        void setWriteFileCallback( WriteFileCallback* cb) { _writeFileCallback = cb; }
216
217        /** Get the const writeFile callback.*/
218        WriteFileCallback* getWriteFileCallback() const { return _writeFileCallback.get(); }
219
220
221        /** Set the callback to use inform the DatabasePager whether a file is located on local or remote file system.*/
222        void setFileLocationCallback( FileLocationCallback* cb) { _fileLocationCallback = cb; }
223
224        /** Get the callback to use inform the DatabasePager whether a file is located on local or remote file system.*/
225        FileLocationCallback* getFileLocationCallback() const { return _fileLocationCallback.get(); }
226
227        /** Set the FileCache that is used to manage local storage of files downloaded from the internet.*/
228        void setFileCache(FileCache* fileCache) { _fileCache = fileCache; }
229
230        /** Get the FileCache that is used to manage local storage of files downloaded from the internet.*/
231        FileCache* getFileCache() const { return _fileCache.get(); }
232
233
234        /** Set the terrain observer_ptr, use to decorate any osgTerrain subgraphs.*/
235        void setTerrain(osg::observer_ptr<osg::Node>& terrain) { _terrain = terrain; }
236
237        /** Get the terrain observer_ptr, use to decorate any osgTerrain subgraphs.*/
238        const osg::observer_ptr<osg::Node>& getTerrain() const { return _terrain; }
239
240        /** Set the parentGroup observer_ptr, where the loaded model is intended to be added */
241        void setParentGroup(osg::observer_ptr<osg::Group>& parentGroup) { _parentGroup= parentGroup; }
242
243        /** Get the parentGroup observer_ptr, where the loaded model is intended to be added */
244        const osg::observer_ptr<osg::Group>& getParentGroup() const { return _parentGroup; }
245
246        bool operator < (const Options &rhs) const;
247        bool operator == (const Options &rhs) const;
248
249    protected:
250
251        virtual ~Options();
252
253        std::string                     _str;
254        FilePathList                    _databasePaths;
255
256        CacheHintOptions                _objectCacheHint;
257        osg::ref_ptr<ObjectCache>       _objectCache;
258
259        PrecisionHint                   _precisionHint;
260        BuildKdTreesHint                _buildKdTreesHint;
261        osg::ref_ptr<AuthenticationMap> _authenticationMap;
262
263        typedef std::map<std::string,void*> PluginDataMap;
264        mutable PluginDataMap _pluginData;
265        typedef std::map<std::string,std::string> PluginStringDataMap;
266        mutable PluginStringDataMap _pluginStringData;
267
268        osg::ref_ptr<FindFileCallback>      _findFileCallback;
269        osg::ref_ptr<ReadFileCallback>      _readFileCallback;
270        osg::ref_ptr<WriteFileCallback>     _writeFileCallback;
271        osg::ref_ptr<FileLocationCallback>  _fileLocationCallback;
272
273        osg::ref_ptr<FileCache>             _fileCache;
274
275        osg::observer_ptr<osg::Node>        _terrain;
276        osg::observer_ptr<osg::Group>       _parentGroup; // Set by the DatabasePager to the node where the requested file will be inserted. NOTE: observer since prent can be dettached whilst DB thread is loading the object
277};
278
279}
280
281#endif // OSGDB_OPTIONS
282