HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
SIM_Cache.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  */
7 
8 #ifndef __SIM_Cache_h__
9 #define __SIM_Cache_h__
10 
11 #include "SIM_API.h"
12 #include <UT/UT_LinkList.h>
13 #include "SIM_Utils.h"
14 #include "SIM_Object.h"
15 #include "SIM_ObjectArray.h"
16 #include "SIM_CacheOptions.h"
17 
18 class SIM_Engine;
19 class SIM_CacheEntry;
20 class SIM_SimulationState;
21 
22 /// This class is the cache for a SIM_Engine.
23 /// It holds all the actual objects for the simulation for the entire
24 /// cached time range.
26 {
27 public:
28  /// Constructor intializes this class with no object data.
29  /// A single cache entry is created to hold any new objects.
30  SIM_Cache();
31  /// Destructor destroys all objects and temp files.
32  ~SIM_Cache();
33 
34  /// Initialize this object with a SIM_Engine pointer. This must be
35  /// done as soon as the SIM_Cache is created.
36  void setEngine(SIM_Engine *engine);
37  /// Returns a reference to our caching option data.
38  const SIM_CacheOptions &getCacheOptions() const;
39  /// Sets the cache options.
40  void setCacheOptions(const SIM_CacheOptions &src);
41 
42  /// Caches the current object data and advances by one time step.
43  /// Basically this consists of creating a copy of all objects in the
44  /// simulation and setting the new current time. If the cache size
45  /// is exceeded, a cache entry will be deleted. A cache entry may
46  /// also get pushed to disk. If caching is disabled, this function
47  /// does nothing except advance the current time.
48  void cacheAndAdvance();
49  /// Tells the cache to move to a new current time.
50  /// Whatever cache entry is the best match for the specfied time will
51  /// be made the current cache entry. If the new time is earlier than any
52  /// cache entry, then the earliest cache entry is used. If the new time
53  /// is later than the latest cache entry, the last entry is used. Note
54  /// that this means the cache's current time won't necessarily be set
55  /// to the requested value. It is up to the SIM_Engine to perform
56  /// simulation steps to get to the actual desired time.
57  void setCurrentTime(const SIM_Time &time);
58  /// Deletes all cache entries after the specified time. The cache
59  /// entry for the specified time itself is also deleted. The cache
60  /// is moved to the entry just prior to the earliest deleted entry.
61  /// If there is insufficient cache to fulfil the request, then nothing
62  /// is changed and the function returns false. Otherwise it returns
63  /// true.
64  bool deleteAfterTime(const SIM_Time &time);
65  /// Clears all cache entries. A single empty cache entry is then
66  /// created to act as the current entry to shich new objects may be
67  /// added.
68  void clear();
69  /// Clears all cache entries. Does not create a cache entry
70  /// to act as a current entry, so the state is invalid and this
71  /// should be shortly deleted.
72  void clearForDestruction();
73  /// Attempts to re-load explicit cache entries from the last
74  /// loaded etnry
75  void preload();
76 
77  /// Returns the time of the current cache entry. This function is
78  /// called by the SIM_Engine::getSimulationTime() function.
79  const SIM_Time &getCurrentTime() const;
80  /// Returns the time of the earliest cache entry. This function is
81  /// called by the SIM_Engine::getEarliestCacheTime() function.
82  const SIM_Time &getEarliestTime() const;
83  const SIM_Time &getLatestTime() const;
84  /// Returns the objects that belong to the current cache entry.
85  /// This function is called by the SIM_Engine getSimulationObject()
86  /// and related functions.
87  SIM_SimulationState &getCurrentSimulationObjects() const;
88  /// Returns the live cached frames
89  void getCachedFrames(UT_IntArray &frames, bool memory) const;
90 
91  /// Returns the specified object at an earlier time step. If the object
92  /// at the exact specified time cannot be found, we create a new object
93  /// by interpolating between the previous and next available states of
94  /// the object.
95  const SIM_Object *getObjectAtTime(const SIM_Object &object,
96  const SIM_Time &time,
97  bool allowinterpolation);
98  /// Returns a non-const object from the specified earlier time. The
99  /// returned value is always a pointer to the passed in object, or a
100  /// substep object. If a time in some earlier timestep is specified,
101  /// the earlier object is copied as a substep object of the current
102  /// time. Otheriwse this function could be used to modify the past.
103  SIM_Object *getAffectorAtTime(SIM_Object &object,
104  const SIM_Time &time,
105  bool allowinterpolation);
106 
107  /// Before the call, 'past_objects' must be a valid array of valid arrays,
108  /// and 'past_times' must be a valid array.
109  /// 'past_objects' must have size 'max_past'
110  /// each element of 'past_objects' must be an array of SIM_Object* of
111  //// size 'num_objects'
112  /// 'past_times' must be an array of size 'max_past'
113  ///
114  /// Output:
115  /// The number of cached frames is returned.
116  /// The cached version of object[oi] at time past_times[i]
117  /// is stored in the array past_objects[i] at location oi,
118  /// for all 0 <= i < "the returned number of cached frames"
119  int getObjectsAtPastTimes(
120  const SIM_Object**const past_objects[],
121  SIM_Time past_times[],
122  const int num_objects,
123  const SIM_Object*const objects[],
124  const int max_past
125  );
126 
127  /// Returns a substep version of the specified object. The substep
128  /// object is always created within the current simulation state
129  /// regardless of the time value. The reason the SIM_Cache is used
130  /// as an intermediary here is so that if we already have an
131  /// interpolated version of the object at the requested time, we
132  /// can convert the interpolated object into a substep (which is
133  /// really different only in the sense of whether the SIM_Cache or
134  /// the SIM_SimulationState owns it).
135  SIM_Object *createSubStepObject(const SIM_Object &object,
136  const SIM_Time &time);
137  /// Deletes any objects from the myInterpolatedObjects array that
138  /// match the provided object id. This function is called by the
139  /// engine just prior to solving the object. The idea is that the
140  /// object may have been used to create an interpolated object prior
141  /// to its solve for a given timestep. After its solve, all the
142  /// interpolation is incorrect, so leaving the interpolated objects
143  /// around is potentially misleading and harmful.
144  void clearInterpolatedObjects(
145  const SIM_ObjectArray &objects);
146  /// This performs the cleanup required after performing a simulation step.
147  /// All temporary interpolated objects are deleted, and any excess cache
148  /// entries in memory are flushed to disk.
149  void postSimulationStep();
150 
151 private:
152  /// Loads a cache entry from disk (if it's not already in memory).
153  void loadFromDisk(SIM_CacheEntry *entry);
154  /// Moves some cache entries from memory to disk if we have too many
155  /// in memory.
156  void ensureCacheCompliesWithOptions();
157  /// Interpolated objects use for display are stored outside of any
158  /// cache entry. This function clears out those interpolated objects.
159  void clearInterpolatedObjects(bool clearsubsteps);
160  /// Utility function used by getObjectAtTime() and getAffectorAtTime().
161  /// It finds the closest existing objects to the requested object.
162  void getBestObjects(const SIM_Object *object,
163  const SIM_Time &time,
164  bool allowinterpolation,
165  const SIM_Object *&matchobject,
166  SIM_Object *&nonconstmatchobject,
167  const SIM_Object *&bestbeforeobject,
168  SIM_Time &bestbeforetime,
169  const SIM_Object *&bestafterobject,
170  SIM_Time &bestaftertime);
171  /// Get the initial entry, which is the simulation state that shows
172  /// up for all times less then zero, and which is copied to be the
173  /// first timestep state when the cache is cleared.
174  SIM_CacheEntry *getInitialEntry();
175  /// Clears the initial entry.
176  void clearInitialEntry();
177  /// Get our current cache entry.
178  SIM_CacheEntry *getCurrentEntry() const;
179  /// Set our current cache entry.
180  void setCurrentEntry(SIM_CacheEntry *newentry);
181 
182  SIM_Engine *myEngine;
183  SIM_CacheOptions myCacheOptions;
184  UT_LinkList myCacheEntries;
185  SIM_CacheEntry *myCurrentEntry;
186  SIM_CacheEntry *myInitialEntry;
187  SIM_ObjectAtTimeMatrix myInterpolatedObjects;
188 
189  /// Do we have any temporary disk caches?
190  /// Does not count explicit entries.
191  /// We use this so we can determine if our getAllowSaveToDisk flag
192  /// needs to be enforced.
193  bool myHasDiskCache;
194 };
195 
196 #endif
197 
GLenum src
Definition: glew.h:2410
GT_API const UT_StringHolder time
Holds pointers to a number of SIM_Object objects.
#define SIM_API
Definition: SIM_API.h:10
This class stores all the caching options used by the SIM_Cache.