HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
OBJ_XformCache.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: OBJ_XformCache.h ( OBJ Library, C++)
7  *
8  * COMMENTS:
9  */
10 
11 #ifndef __OBJ_XformCacher__
12 #define __OBJ_XformCacher__
13 
14 #include "OBJ_API.h"
15 #include <UT/UT_Cache.h>
16 #include <UT/UT_Matrix4.h>
17 #include <UT/UT_SpinLock.h>
18 #include <UT/UT_ThreadSafeCache.h>
19 #include <UT/UT_VectorTypes.h>
20 #include <OP/OP_Version.h>
21 
22 class CMD_Args;
23 class OBJ_XformCacheData;
24 class OBJ_XformCacheTag;
25 class OBJ_XformCacheHashTable;
26 
27 /// The OBJ_XformCache maintains a table of recently calculated transforms
28 /// which describe world position and orientation of objects.
29 ///
30 /// It can also watch memory usage to see what transform matrices should be
31 /// removed from the table.
33 {
34 public:
35 
36  // specifies transforms that a single object is able to cache
38  {
39  WORLD_XFORM, //world transform of an object
40  LOCAL_XFORM, //local transform of an object
41  PRECONSTRAINTS_XFORM //preconstraints transform of an object
42  };
43 
44  // specifies the results returned by cache lookups
46  {
47  HIT, // lookup is successful
48  MISS_VERSION, // lookup failed: invalidated data
49  MISS_DATA // lookup failed: data never cached
50  };
51 
52  // some constants
53  enum
54  {
55  // default memory limit for the cache in bytes NB: for a production size
56  // scene with three characters there are around 1000 bones, which take
57  // about 350kB per frame to cache 1000 objects. So 300 frames take
58  // around 100MB of cache memory.
59  DEFAULT_CACHE_SIZE_KB = 150*1024
60  };
61 
62 
63 public:
65  ~OBJ_XformCache();
66 
67  /// Obtains the transform matrix cache used by all objects
68  static OBJ_XformCache *getCache();
69 
70  /// querries the cache for the transform matrix
71  /// INPUTS:
72  /// id - the unique identification number of the operator
73  /// time - the time at which the xform is applied to the object
74  /// type - tranformation type
75  /// version - version of parameters used to construct the xform
76  /// OUTPUT:
77  /// xform - on cache hit, the transform matrix, otherwise unchanged
78  /// RETURNS:
79  /// the status of the lookup (hit or miss)
80  ///
81  const UT_DMatrix4 & getXform( int id, fpreal time,
82  OBJ_XformType type,
83  OP_VERSION version,
84  OBJ_LookupStatus &status );
85 
86  /// sets the transform matrix in the cache
87  /// INPUTS:
88  /// id - the unique identification number of the operator
89  /// time - the time at which the xform is applied to the object
90  /// type - tranformation type
91  /// version - version of parameters used to construct the xform
92  /// RETURNS:
93  /// true: if succeeded
94  /// false: if failed
95  ///
96  bool setXform( int id, fpreal time,
97  OBJ_XformType type,
98  OP_VERSION version,
99  const UT_DMatrix4 &xform );
100 
101  // TODO: add higher performance version of getXform, which returns
102  // cache data container to be set directly by cache caller
103  // on cache miss (determined by version ID)
104 
105 
106  /// Used as the interface to objcache, which is installed in
107  /// MOT_Command.C
108  void parseCommand( CMD_Args &args );
109 
110 
111  /// Sets the new memory limit for the cache size in bytes
112  void setMemoryLimit( int64 max_memory );
113 
114  /// Clears the cache and frees memory
115  void clear();
116 
118 
120  {
121  MEMORY_CHECK_NEVER, // never track memory size
122  MEMORY_CHECK_ALWAYS // always watch for memory limit
123  };
124 
125  OBJ_MemoryState getMemoryState() const;
126 
127 protected:
128  // the UT_Cache interface
129  virtual const char *utGetCacheName() const
130  {return "Object Transform Cache";}
131  virtual int64 utGetCurrentSize() const
132  { return entries()* getEntryMemUsage(); }
133 
134  virtual bool utHasMaxSize() const { return true; }
135  virtual int64 utGetMaxSize() const
136  { return myMaxEntries* getEntryMemUsage(); }
137  virtual void utSetMaxSize(int64 size);
138 
139  virtual int64 utReduceCacheSizeBy(int64 amount);
140 
141 private: //methods
142  // sets the give tag as most recently used
143  void setMRU(OBJ_XformCacheTag *tag);
144  // remove least recently used entry
145  void deallocateItem(OBJ_XformCacheTag *tag);
146  // returns the memory size of a cache entry
147  static int64 getEntryMemUsage();
148  // returns number of entries in the cache (NOT THREAD-SAFE!)
149  int64 entries() const;
150 
151 private:
152  /// This stores the transformation matrices computed previously
153  OBJ_XformCacheHashTable *myData;
154 
155  /// Access policy
156  Policy myCachePolicy;
157 
158  // Memory management variables
159  int64 myMaxEntries; //memory limit (# of xforms)
160 
161  const UT_DMatrix4 theIdentity; // Identify matrix when failing and returning a const reference.
162 private:
163  friend class OBJ_XformCacheTag;
164 };
165 
166 
167 #endif
168 
uint64 OP_VERSION
Definition: OP_Version.h:6
virtual int64 utGetMaxSize() const
GLsizeiptr size
Definition: glcorearb.h:663
long long int64
Definition: SYS_Types.h:106
virtual int64 utReduceCacheSizeBy(int64 amount)=0
virtual bool utHasMaxSize() const
optional - override if the cache has a well defined maximum size
Common base class for various caches.
Definition: UT_Cache.h:21
double fpreal
Definition: SYS_Types.h:269
png_infop png_sPLT_tpp entries
Definition: png.h:2481
UT_ThreadSafeCache< UT_RecursiveSpinLock > Policy
virtual const char * utGetCacheName() const
required - return the english name for this cache.
virtual int64 utGetCurrentSize() const
required - return the current cache size, in bytes
virtual void utSetMaxSize(int64)
Definition: UT_Cache.h:45
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:107
#define OBJ_API
Definition: OBJ_API.h:10