HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
FS_FileResolver.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: FS_FileResolver.h (FS Library, C++)
7  *
8  * COMMENTS: This class resolves the data specified by its name. The name can
9  * a file path or an "op:" path.
10  *
11  * In applications that can cook the op data (eg, Houdini and
12  * Batch), the resolver instance actually searches out the node and
13  * asks it for the data, then it creates a stream and returns it as
14  * a file reader object. To release this temporarily created
15  * stream, the requester needs to let the resolver know so that
16  * it can relinquish it.
17  *
18  * In applications that don't have access to nodes (eg, Mantra),
19  * the resolver instance needs to rely on the data given to
20  * it (eg, inside the IFD stream). Since other entities (eg,
21  * shaders) still refer to the data as "op:", the resolver
22  * needs to figure out which data to return for each request.
23  * The data is returned in a form of FS_Reader, but the actual
24  * data may be in memory, in a temp file on disk, or elsewhere.
25  * The requester may notify the resolver that it is done with the
26  * data and to relinquish it, but the resolver will probably need
27  * to keep the data around for the future requests, since there is
28  * no source for that data (no nodes, and IFD has been already
29  * sourced before).
30  *
31  */
32 
33 #ifndef __FS_FileResolver__
34 #define __FS_FileResolver__
35 
36 #include "FS_API.h"
37 #include <SYS/SYS_Types.h>
38 #include <UT/UT_String.h>
39 #include <UT/UT_StringHolder.h>
40 #include <UT/UT_SymbolTable.h>
41 
42 class UT_IStream;
43 class FS_Reader;
44 
45 
46 //=============================================================================
47 /// Provides various options for creating and obtaining the file data.
49 {
50 public:
51  /// Constructor.
54 
55  /// Assignment operator.
56  const FS_FileResolverOptions & operator=(
57  const FS_FileResolverOptions & src );
58 
59  /// Gets the time at which a node should be evaluated to obtain the data.
60  fpreal getTime() const
61  { return myTime; }
62  void setTime( fpreal time )
63  { myTime = time; }
64 
65  /// Gets the extension for the file that will contain the resolved data.
66  /// It indirectly determines the data type for stream readers and writers.
68  { return myFileExtension; }
70  { myFileExtension = ext; }
71 
72  /// Checks if the file should be treated as an environment map.
73  bool getIsEnvMap() const
74  { return myIsEnvMap; }
75  void setIsEnvMap( bool env_map )
76  { myIsEnvMap = env_map; }
77 
78 
79 private:
80  UT_StringHolder myFileExtension; // extension of the data file
81  fpreal myTime; // node evaluation time
82  bool myIsEnvMap; // is environment map
83 };
84 
85 
86 //=============================================================================
87 /// Maps the operator paths (eg, "op:/path"), and other data sources,
88 /// to file readers that access their data.
90 {
91 public:
92  /// Constructor.
94  /// Destructor.
95  virtual ~FS_FileResolver();
96 
97  /// Sets the instance that will resolve the operator paths to data files.
98  static void setResolver( FS_FileResolver * resolver );
99 
100  /// Returns the currently set resolver.
101  static FS_FileResolver * getResolver();
102 
103 
104  /// Checks if the resolver can provide the file data for the given name.
105  // TODO: this method may need to take FS_FileResolverOptions argument
106  virtual bool getCanResolve( const char * name ) = 0;
107 
108  /// @brief Creates a new reader object given the file (or data) name.
109  ///
110  /// The returned reader can be used to read the data, and when finished,
111  /// it should be freed by passing it to the FS_FileResolver::deleteReader()
112  /// method.
113  ///
114  /// @param opts The options that indicate how the data should be
115  /// generated, if applicable. Eg, it contains the evaluation
116  /// time for nodes or the file format in which the data
117  /// should be available.
118  ///
119  /// @param name The name of the data to be read. Can be a file
120  /// specified with "file:/path" or an operator node
121  /// data specified with "op:/path", or any other standard
122  /// way of specifying data in Houdini.
123  //
124  /// @return The reader for the specified data.
125  ///
126  virtual FS_Reader * newReader( const FS_FileResolverOptions & opts,
127  const char * name ) = 0;
128 
129 
130  /// Closes stream (if they are still open) and deletes the reader.
131  /// After this call, the reader pointer will no longer be valid.
132  ///
133  /// @param reader The reader to be freed.
134  ///
135  virtual void deleteReader( FS_Reader * reader ) = 0;
136 
137 
138  /// Obtains the file path to the data of a given name. On success,
139  /// 'file_path' will contain a non-epnty file path. This file path
140  /// should be then released using FS_FileResolver::relinquishFilePath().
141  ///
142  /// @param opts The options that describe the data.
143  /// @param name The name of the data available in the file.
144  /// @param file_path The output parameter which will have the
145  /// path of the file that contains the data. If
146  /// the request fails, the path will be an empty string.
147  virtual void acquireFilePath(
148  const FS_FileResolverOptions & opts,
149  const char * name,
150  UT_String & file_path ) = 0;
151 
152  /// Releases the file path and allows the resolver to (optionally) free
153  /// the file resources.
154  ///
155  /// @param file_path The file path previously obtained with
156  /// FS_FileResolver::acquireFilePath().
157  virtual void relinquishFilePath( const char * file_path ) = 0;
158 
159  /// Adds the data to the resolver, so that the resolver can handle
160  /// future requests for the data given this name.
161  ///
162  /// @param opts Options describe how the data should be interpreted.
163  ///
164  /// @param name The name of the resource. Future requests for this
165  /// resource using FS_FileResolver::newReader() will returno
166  /// a reader that provides this data.
167  ///
168  /// @param data The stream containing the data. The resolver will
169  /// read in and store this data for future use.
170  virtual void registerFile(const FS_FileResolverOptions &opts,
171  const UT_StringHolder &name,
172  UT_IStream & data );
173 
174  /// Returns an instance-unique identifier for a path that can be used to
175  /// check if the underlying resource data has changed, and should be
176  /// re-read by the clients of this class.
177 
178  /// @param name The name of the data to get the identifier for.
179  ///
180  /// @return The revision id of the data. Returns 0 if the resource
181  /// does not exist or revision IDs are not supported.
182  virtual int getRevisionID(const char *name) = 0;
183 protected:
184 
185  /// Contains details about the data that the resolver can provide.
187  {
188  public:
189  // constructor
191  const UT_StringHolder &file_name,
192  const FS_FileResolverOptions &opts);
193 
194  // Accessors.
195  const UT_StringHolder &getName() const { return myName; }
196  const UT_StringHolder &getFileName() const { return myFileName; }
197 
199  { return myOptions; }
200 
201  private:
202  /// Name of the resource this entry represents.
203  UT_StringHolder myName;
204 
205  /// The file name in which the resource data is saved.
206  UT_StringHolder myFileName;
207 
208  /// Options with which the file has been crated.
209  FS_FileResolverOptions myOptions;
210  };
211 
212 
213  /// Adds the file to the table.
214  /// The resolver takes ownership of the file and will delete it
215  /// in the destructor, unless it is unregistered from the table beforehand,
216  /// with FS_FileResolver::unregisterFile().
217  void registerFile(
218  const FS_FileResolverOptions &opts,
219  const UT_StringHolder &name,
220  const UT_StringHolder &file_path );
221 
222  /// Removes the file from table, and deletes the file if 'delete_file' is
223  /// true.
224  void unregisterFile( const UT_StringRef &name,
225  bool delete_file );
226 
227  /// Looks up the table entry for the given name key and returns the
228  /// entry. If not found, returns NULL.
229  FS_ResolverFileEntry * findFileInTable( const char * name );
230 
231 private:
232  /// Adds the file to the table.
233  void addFileToTable(const UT_StringHolder &name,
234  FS_ResolverFileEntry *entry);
235 
236  /// Removes the file entry from the table. If 'delete_file' is true,
237  /// the file on disk is also deleted.
238  void removeFileFromTable(const UT_StringRef &name,
239  bool delete_file);
240 
241 
242  /// Deletes the entry and any temporary files that hold the resource data.
243  /// If 'delete_file' is true, the file on disk is also deleted.
244  void deleteEntry(FS_ResolverFileEntry *entry,
245  bool delete_file );
246 
247 
248 private:
249  /// The current resolver.
250  static FS_FileResolver *theResolver;
251 
252  /// The table that maps the data name to the file containing that data.
254 };
255 
256 
257 //=============================================================================
258 /// Utility class for auto destruction and cleanup of the file resolver.
260 {
261 public:
262  /// Constructor
264 
265  /// Destructor. Deletes the resolver it holds (if not NULL), and if
266  /// it is the same as the current global resolver, it resets it to NULL.
268 
269  /// Accessor for the resolver it holds.
271  { return myResolver; }
272 
273  /// Sets the resolver it cleans up after.
274  void setResolver( FS_FileResolver * resolver )
275  { myResolver = resolver; }
276 
277  /// Destroys the resolver right away rather than waiting for the
278  /// destructor to be invoked.
279  void destroyResolver();
280 
281 private:
282  // the resolver to clean up after
283  FS_FileResolver * myResolver;
284 
285 };
286 
287 #endif
288 
const UT_StringHolder & getFileExtension() const
Class for reading files.
Definition: FS_Reader.h:30
void setFileExtension(const UT_StringHolder &ext)
void setTime(fpreal time)
Utility class for auto destruction and cleanup of the file resolver.
FS_FileResolver * getResolver() const
Accessor for the resolver it holds.
const UT_StringHolder & getFileName() const
GLboolean * data
Definition: glcorearb.h:130
GLuint const GLchar * name
Definition: glcorearb.h:785
double fpreal
Definition: SYS_Types.h:263
Provides various options for creating and obtaining the file data.
void setResolver(FS_FileResolver *resolver)
Sets the resolver it cleans up after.
bool getIsEnvMap() const
Checks if the file should be treated as an environment map.
Contains details about the data that the resolver can provide.
void setIsEnvMap(bool env_map)
const UT_StringHolder & getName() const
#define FS_API
Definition: FS_API.h:10
fpreal getTime() const
Gets the time at which a node should be evaluated to obtain the data.
GLenum src
Definition: glcorearb.h:1792
const FS_FileResolverOptions & getOptions() const