HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
GA_IntrinsicManager.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: GA_IntrinsicManager.h ( GA Library, C++)
7  *
8  * COMMENTS:
9  */
10 
11 #ifndef __GA_IntrinsicManager__
12 #define __GA_IntrinsicManager__
13 
14 #include "GA_API.h"
15 #include "GA_Types.h"
16 
17 #include <UT/UT_Options.h>
18 #include <UT/UT_Array.h>
19 #include <UT/UT_ArrayMap.h>
20 #include <UT/UT_StringHolder.h>
21 #include <UT/UT_ArrayStringMap.h>
22 
23 #include <stddef.h>
24 
25 
26 class GA_IntrinsicDef;
27 class UT_StringArray;
28 
29 
30 /// @brief Manager to keep track of global handle to name mappings
31 ///
32 /// Each GA_PrimitiveFactory maintains a list of intrinsic attributes.
33 /// These attribute provide a mechanism to query information about primitives
34 /// without having knowledge of the actual structure of the primitive.
35 ///
36 /// There is a unique handle (or id) for each attribute name. This class
37 /// maintains the mapping between name and handle.
38 ///
40 {
41 public:
42  /// Get the global id associated with a given token
43  static GA_GlobalIntrinsic getGlobalHandle(const UT_StringRef &token);
44 
45  /// Register a global token (returns the existing handle if it's found)
46  static GA_GlobalIntrinsic registerGlobalHandle(const UT_StringHolder &token);
47 
48  /// Find the token associated with the given global handle
49  static const UT_StringHolder &getGlobalName(GA_GlobalIntrinsic handle);
50 
51  /// Return the number of local handles defined in the manager
52  int getLocalEntries() const
53  { return myAttributes.entries(); }
54 
55  /// Extract all attribute names
56  void extractNames(UT_StringArray &names) const;
57 
58  /// @{
59  /// Mapping between global and local attributes
60  GA_LocalIntrinsic getLocalHandle(const UT_StringRef &token) const;
61  GA_LocalIntrinsic getLocalHandle(GA_GlobalIntrinsic ghandle) const;
63  {
64  return isValidHandle(lhandle)
65  ? myAttributes(lhandle)->getGlobalId()
67  }
68  /// @}
69 
70  /// Look up an attribute name from the given handle
72  {
73  return isValidHandle(handle)
74  ? myAttributes(handle)->getName()
76  }
77 
78  /// @{
79  /// Get the attribute storage (passed in during registration)
81  { return getStorage(getLocalHandle(name)); }
83  {
84  return isValidHandle(handle)
85  ? myAttributes(handle)->getStorage()
87  }
88  /// @}
89 
90  /// @{
91  /// Get the attribute storage (passed in during registration)
92  bool getReadOnly(const UT_StringRef &name) const
93  { return getStorage(getLocalHandle(name)); }
94  bool getReadOnly(GA_LocalIntrinsic handle) const
95  {
96  return isValidHandle(handle)
97  ? myAttributes(handle)->getReadOnly()
98  : true; // invalid handles are read only
99  }
100  /// @}
101 
102  /// @{
103  /// Get the attribute's user id (passed in during registration)
104  int getUserId(const UT_StringRef &name) const
105  { return getUserId(getLocalHandle(name)); }
106  int getUserId(GA_LocalIntrinsic handle) const
107  {
108  return isValidHandle(handle)
109  ? myAttributes(handle)->getUserId()
110  : -1;
111  }
112  /// @}
113 
114  /// @{
115  /// Get the attribute options (passed in during registration)
116  const UT_Options *getOptions(const UT_StringRef &name) const
117  { return getOptions(getLocalHandle(name)); }
119  {
120  return isValidHandle(handle)
121  ? &myAttributes(handle)->getOptions()
122  : NULL;
123  }
124  /// @}
125 
126  /// The Registrar class is used to register intrinsic attributes
127  /// Sample usage for a GA_Primitive sub-class might be something like:
128  /// @code
129  /// static GA_IntrinsicDef theClassIntrinsics;
130  ///
131  /// GA_IntrinsicManager::Registrar
132  /// MyClass::registerIntrinsics(GA_PrimitiveDefinition &def)
133  /// {
134  /// GA_IntrinsicManager::Registrar r =
135  /// MyBaseClass:registerIntrinsics(def);
136  /// if (r.start(theClassIntrinsics))
137  /// {
138  /// r.addAttribute(GA_STORECLASS_STRING, "intrinsic1", 0, true);
139  /// r.addAttribute(GA_STORECLASS_FLOAT, "intrinsic2", 1, true);
140  /// }
141  /// UT_ASSERT(r.getOk());
142  /// return r;
143  /// }
144  /// @endcode
145  class Registrar
146  {
147  public:
148  /// Copy constructor
150  : myManager(r.myManager)
151  , myDef(r.myDef)
152  , myOk(r.myOk)
153  {}
154  /// Destructor
156  {
157  end(); // Close off last definition
158  }
159  /// Assignment operator
161  {
162  myManager = r.myManager;
163  return *this;
164  }
165 
166  /// Start defining attributes for the given intrinsic definition
168  {
169  end();
170  if (myOk)
171  {
172  myOk = myManager->startDefinition(def);
173  myDef = &def;
174  }
175  return myOk;
176  }
177  /// Method to add an intrinsic attribute.
178  /// - The name must be unique through the inheritance hierarchy
179  /// - The @c user_id is used for evaluation (see GA_IntrinsicEval)
181  const UT_StringRef &name,
182  int user_id,
183  bool read_only,
184  const UT_Options *options=NULL)
185  {
187  if (myOk)
188  {
189  h = myManager->addAttribute(store,
190  name, user_id, read_only,
191  options);
192  if (!GAisValidGlobalIntrinsic(h))
193  myOk = false;
194  }
195  else
197  return h;
198  }
199  /// Return status of the operation
200  bool getOk() const { return myOk; }
201 
202  private:
203  void end()
204  {
205  if (myOk && myDef)
206  myOk = myManager->endDefinition(*myDef);
207  }
208  Registrar(GA_IntrinsicManager &man)
209  : myManager(&man)
210  , myDef(NULL)
211  , myOk(true)
212  {
213  }
214  friend class GA_Primitive;
215  friend class GA_Detail;
216  GA_IntrinsicManager *myManager;
217  GA_IntrinsicDef *myDef;
218  bool myOk;
219  };
220 
221  /// Iterator class to iterate
222  /// Usage: @code
223  /// GA_IntrinsicManager::iterator it;
224  /// for (it = manager.begin(); !it.atEnd(); ++it) ...
225  /// @endcode
227  {
228  public:
229  /// Simple default constructor
231  : myManager(NULL),
232  myCurrent(0),
233  myEntries(0) { }
234  /// Copy constructor
236  {
237  *this = src;
238  }
239  /// Destructor
241  /// Assignment operator
243  {
244  myManager = src.myManager;
245  myCurrent = src.myCurrent;
246  myEntries = src.myEntries;
247  return *this;
248  }
249  /// Increment operator
250  iterator &operator++() { advance(); return *this; }
251 
252  // No post increment as it is harmful.
253 
254  /// Test to see if the iteration is complete
255  bool atEnd() const
256  {
257  return !myManager || myCurrent >= myEntries;
258  }
259  /// Advance to the next iteration
260  void advance() { myCurrent++; }
261 
262  /// Get the current attribute token
263  const UT_StringHolder &getToken() const
264  { return myManager->getName(myCurrent); }
266  { return myCurrent; }
267  /// Get the current attribute handle (global id)
268  int getIndex() const
269  { return myCurrent; }
270  private:
271  /// Private c-tor: Access this through the begin() method
272  iterator(const GA_IntrinsicManager *manager)
273  : myManager(manager),
274  myCurrent(0),
275  myEntries(manager->getLocalEntries())
276  {
277  }
278  const GA_IntrinsicManager *myManager;
279  GA_LocalIntrinsic myCurrent; // Iterate over the locals
280  int myEntries;
281 
282  friend class GA_IntrinsicManager;
283  };
284 
285  /// Start traversal of intrinsic attributes names
286  iterator begin() const { return iterator(this); }
287 
288 private:
289  /// Check to see if handle is in bounds
290  inline bool isValidHandle(GA_LocalIntrinsic h) const
291  { return h >= 0 && h < myAttributes.entries(); }
292 
293  /// The internal definition of an attribute
294  class ga_IntrinsicAttribute
295  {
296  public:
297  ga_IntrinsicAttribute(GA_StorageClass store,
298  const UT_StringHolder &name,
299  GA_GlobalIntrinsic global_id,
300  GA_LocalIntrinsic local_id,
301  int user_id,
302  bool read_only,
303  const UT_Options *options)
304  : myOptions()
305  , myName(name)
306  , myGlobalId(global_id)
307  , myLocalId(local_id)
308  , myUserId(user_id)
309  , myStorage(store)
310  , myReadOnly(read_only)
311  {
312  if (options)
313  myOptions = *options;
314  }
315  ~ga_IntrinsicAttribute() {}
316 
317  const UT_StringHolder &getName() const { return myName; }
318  GA_StorageClass getStorage() const { return myStorage; }
319  const UT_Options &getOptions() const { return myOptions; }
320  int getGlobalId() const { return myGlobalId; }
321  int getLocalId() const { return myLocalId; }
322  int getUserId() const { return myUserId; }
323  bool getReadOnly() const { return myReadOnly; }
324  private:
325  UT_Options myOptions;
326  UT_StringHolder myName;
327  GA_GlobalIntrinsic myGlobalId;
328  GA_LocalIntrinsic myLocalId;
329  int myUserId;
330  GA_StorageClass myStorage;
331  bool myReadOnly;
332  };
333 
334  /// @{
335  /// When registering attributes, you *must* bracket the attribute
336  /// definitions within a startDefinition/endDefinition pair. Code usually
337  /// looks like: @code
338  /// static GA_IntrinsicDef theIntrinsicDef;
339  /// MyClass::registerIntrinsicAttributes(GA_IntrinsicManager &man) {
340  /// MyBaseClass::registerIntrinsicAttributes(man);
341  /// man.startDefinition(theIntrinsicDef);
342  /// man.addAttribute(storage, "foo", 0, ...);
343  /// man.addAttribute(storage, "bar", 1, ...);
344  /// man.endDefinition(theIntrinsicDef);
345  /// }
346  /// @endcode
347  /// @see GA_IntrinsicEval
348  bool startDefinition(GA_IntrinsicDef &def);
349  bool endDefinition(GA_IntrinsicDef &def);
350  /// @}
351  /// Add an local intrinsic. If there's a name collision within this
352  /// object, this method will fail by returning an invalid handle (see
353  /// GAisValidGlobalIntrinsic()) The user_id is the value returned by @c
354  /// getUserId() and usually refers to an enum private to the caller.
355  /// A copy is made of the options if passed in.
356  GA_GlobalIntrinsic addAttribute(GA_StorageClass store, const UT_StringRef &name,
357  int user_id, bool read_only,
358  const UT_Options *options);
359 
360 
363 
364  UT_ArrayStringMap<ga_IntrinsicAttribute *> myTokenToLocalTable;
365  UT::ArrayMap<GA_GlobalIntrinsic, int> myGlobalToLocalTable;
367 
368  friend class GA_PrimitiveFactory;
370  friend class Registrar;
371 };
372 
373 #endif
GA_GlobalIntrinsic getGlobalHandle(GA_LocalIntrinsic lhandle) const
bool getOk() const
Return status of the operation.
const UT_StringHolder & getToken() const
Get the current attribute token.
GA_StorageClass
Definition: GA_Types.h:68
int getLocalEntries() const
Return the number of local handles defined in the manager.
Manager to keep track of global handle to name mappings.
#define GA_API
Definition: GA_API.h:12
Stores information about intrinsic attributes for classes.
int GA_GlobalIntrinsic
Definition: GA_Types.h:671
int GA_LocalIntrinsic
Definition: GA_Types.h:670
iterator(const iterator &src)
Copy constructor.
static const UT_StringHolder theEmptyString
GLuint GLuint end
Definition: glcorearb.h:474
const UT_Options * getOptions(GA_LocalIntrinsic handle) const
void advance()
Advance to the next iteration.
const UT_Options * getOptions(const UT_StringRef &name) const
GLuint const GLchar * name
Definition: glcorearb.h:785
bool getReadOnly(GA_LocalIntrinsic handle) const
GA_GlobalIntrinsic addAttribute(GA_StorageClass store, const UT_StringRef &name, int user_id, bool read_only, const UT_Options *options=NULL)
const iterator & operator=(const iterator &src)
Assignment operator.
int getUserId(GA_LocalIntrinsic handle) const
GA_StorageClass getStorage(const UT_StringRef &name) const
GLfloat GLfloat GLfloat GLfloat h
Definition: glcorearb.h:2001
A map of string to various well defined value types.
Definition: UT_Options.h:42
Registrar & operator=(const Registrar &r)
Assignment operator.
iterator & operator++()
Increment operator.
bool start(GA_IntrinsicDef &def)
Start defining attributes for the given intrinsic definition.
Registrar(const Registrar &r)
Copy constructor.
bool getReadOnly(const UT_StringRef &name) const
const UT_StringHolder & getName(GA_LocalIntrinsic handle) const
Look up an attribute name from the given handle.
int getIndex() const
Get the current attribute handle (global id)
Container class for all geometry.
Definition: GA_Detail.h:95
bool atEnd() const
Test to see if the iteration is complete.
iterator()
Simple default constructor.
Definition of a geometric primitive.
GLboolean r
Definition: glcorearb.h:1221
GA_LocalIntrinsic getLocalHandle() const
iterator begin() const
Start traversal of intrinsic attributes names.
int getUserId(const UT_StringRef &name) const
GA_StorageClass getStorage(GA_LocalIntrinsic handle) const
#define GA_INVALID_INTRINSIC_HANDLE
Definition: GA_Types.h:672
GLenum src
Definition: glcorearb.h:1792