HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups 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  };
42 
43  // specifies the results returned by cache lookups
45  {
46  HIT, // lookup is successful
47  MISS_VERSION, // lookup failed: invalidated data
48  MISS_DATA // lookup failed: data never cached
49  };
50 
51  // some constants
52  enum
53  {
54  // default memory limit for the cache in bytes NB: for a production size
55  // scene with three characters there are around 1000 bones, which take
56  // about 350kB per frame to cache 1000 objects. So 300 frames take
57  // around 100MB of cache memory.
58  DEFAULT_CACHE_SIZE_KB = 150*1024
59  };
60 
61 
62 public:
64  ~OBJ_XformCache();
65 
66  /// Obtains the transform matrix cache used by all objects
67  static OBJ_XformCache *getCache();
68 
69  /// querries the cache for the transform matrix
70  /// INPUTS:
71  /// id - the unique identification number of the operator
72  /// time - the time at which the xform is applied to the object
73  /// type - tranformation type
74  /// version - version of parameters used to construct the xform
75  /// OUTPUT:
76  /// xform - on cache hit, the transform matrix, otherwise unchanged
77  /// RETURNS:
78  /// the status of the lookup (hit or miss)
79  ///
80  const UT_DMatrix4 & getXform( int id, fpreal time,
81  OBJ_XformType type,
83  OBJ_LookupStatus &status );
84 
85  /// sets the transform matrix in the cache
86  /// INPUTS:
87  /// id - the unique identification number of the operator
88  /// time - the time at which the xform is applied to the object
89  /// type - tranformation type
90  /// version - version of parameters used to construct the xform
91  /// RETURNS:
92  /// true: if succeeded
93  /// false: if failed
94  ///
95  bool setXform( int id, fpreal time,
96  OBJ_XformType type,
98  const UT_DMatrix4 &xform );
99 
100  // TODO: add higher performance version of getXform, which returns
101  // cache data container to be set directly by cache caller
102  // on cache miss (determined by version ID)
103 
104 
105  /// Used as the interface to objcache, which is installed in
106  /// MOT_Command.C
107  void parseCommand( CMD_Args &args );
108 
109 
110  /// Sets the new memory limit for the cache size in bytes
111  void setMemoryLimit( int64 max_memory );
112 
113  /// Clears the cache and frees memory
114  void clear();
115 
117 
119  {
120  MEMORY_CHECK_NEVER, // never track memory size
121  MEMORY_CHECK_ALWAYS // always watch for memory limit
122  };
123 
124  OBJ_MemoryState getMemoryState() const;
125 
126 protected:
127  // the UT_Cache interface
128  virtual const char *utGetCacheName() const
129  {return "Object Transform Cache";}
130  virtual int64 utGetCurrentSize() const
131  { return entries()* getEntryMemUsage(); }
132 
133  virtual bool utHasMaxSize() const { return true; }
134  virtual int64 utGetMaxSize() const
135  { return myMaxEntries* getEntryMemUsage(); }
136  virtual void utSetMaxSize(int64 size);
137 
138  virtual int64 utReduceCacheSizeBy(int64 amount);
139 
140 private: //methods
141  // sets the give tag as most recently used
142  void setMRU(OBJ_XformCacheTag *tag);
143  // remove least recently used entry
144  void deallocateItem(OBJ_XformCacheTag *tag);
145  // returns the memory size of a cache entry
146  static int64 getEntryMemUsage();
147  // returns number of entries in the cache (NOT THREAD-SAFE!)
148  int64 entries() const;
149 
150 private:
151  /// This stores the transformation matrices computed previously
152  OBJ_XformCacheHashTable *myData;
153 
154  /// Access policy
155  Policy myCachePolicy;
156 
157  // Memory management variables
158  int64 myMaxEntries; //memory limit (# of xforms)
159 
160  const UT_DMatrix4 theIdentity; // Identify matrix when failing and returning a const reference.
161 private:
162  friend class OBJ_XformCacheTag;
163 };
164 
165 
166 #endif
167 
uint64 OP_VERSION
Definition: OP_Version.h:6
GT_API const UT_StringHolder time
virtual int64 utGetMaxSize() const
GLsizeiptr size
Definition: glcorearb.h:663
long long int64
Definition: SYS_Types.h:107
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
GT_API const UT_StringHolder version
double fpreal
Definition: SYS_Types.h:270
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