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  /// Attempts to re-load explicit cache entries from the last
70  /// loaded etnry
71  void preload();
72 
73  /// Returns the time of the current cache entry. This function is
74  /// called by the SIM_Engine::getSimulationTime() function.
75  const SIM_Time &getCurrentTime() const;
76  /// Returns the time of the earliest cache entry. This function is
77  /// called by the SIM_Engine::getEarliestCacheTime() function.
78  const SIM_Time &getEarliestTime() const;
79  const SIM_Time &getLatestTime() const;
80  /// Returns the objects that belong to the current cache entry.
81  /// This function is called by the SIM_Engine getSimulationObject()
82  /// and related functions.
83  SIM_SimulationState &getCurrentSimulationObjects() const;
84  /// Returns the live cached frames
85  void getCachedFrames(UT_IntArray &frames, bool memory) const;
86 
87  /// Returns the specified object at an earlier time step. If the object
88  /// at the exact specified time cannot be found, we create a new object
89  /// by interpolating between the previous and next available states of
90  /// the object.
91  const SIM_Object *getObjectAtTime(const SIM_Object &object,
92  const SIM_Time &time,
93  bool allowinterpolation);
94  /// Returns a non-const object from the specified earlier time. The
95  /// returned value is always a pointer to the passed in object, or a
96  /// substep object. If a time in some earlier timestep is specified,
97  /// the earlier object is copied as a substep object of the current
98  /// time. Otheriwse this function could be used to modify the past.
99  SIM_Object *getAffectorAtTime(SIM_Object &object,
100  const SIM_Time &time,
101  bool allowinterpolation);
102 
103  /// Before the call, 'past_objects' must be a valid array of valid arrays,
104  /// and 'past_times' must be a valid array.
105  /// 'past_objects' must have size 'max_past'
106  /// each element of 'past_objects' must be an array of SIM_Object* of
107  //// size 'num_objects'
108  /// 'past_times' must be an array of size 'max_past'
109  ///
110  /// Output:
111  /// The number of cached frames is returned.
112  /// The cached version of object[oi] at time past_times[i]
113  /// is stored in the array past_objects[i] at location oi,
114  /// for all 0 <= i < "the returned number of cached frames"
115  int getObjectsAtPastTimes(
116  const SIM_Object**const past_objects[],
117  SIM_Time past_times[],
118  const int num_objects,
119  const SIM_Object*const objects[],
120  const int max_past
121  );
122 
123  /// Returns a substep version of the specified object. The substep
124  /// object is always created within the current simulation state
125  /// regardless of the time value. The reason the SIM_Cache is used
126  /// as an intermediary here is so that if we already have an
127  /// interpolated version of the object at the requested time, we
128  /// can convert the interpolated object into a substep (which is
129  /// really different only in the sense of whether the SIM_Cache or
130  /// the SIM_SimulationState owns it).
131  SIM_Object *createSubStepObject(const SIM_Object &object,
132  const SIM_Time &time);
133  /// Deletes any objects from the myInterpolatedObjects array that
134  /// match the provided object id. This function is called by the
135  /// engine just prior to solving the object. The idea is that the
136  /// object may have been used to create an interpolated object prior
137  /// to its solve for a given timestep. After its solve, all the
138  /// interpolation is incorrect, so leaving the interpolated objects
139  /// around is potentially misleading and harmful.
140  void clearInterpolatedObjects(
141  const SIM_ObjectArray &objects);
142  /// This performs the cleanup required after performing a simulation step.
143  /// All temporary interpolated objects are deleted, and any excess cache
144  /// entries in memory are flushed to disk.
145  void postSimulationStep();
146 
147 private:
148  /// Loads a cache entry from disk (if it's not already in memory).
149  void loadFromDisk(SIM_CacheEntry *entry);
150  /// Moves some cache entries from memory to disk if we have too many
151  /// in memory.
152  void ensureCacheCompliesWithOptions();
153  /// Interpolated objects use for display are stored outside of any
154  /// cache entry. This function clears out those interpolated objects.
155  void clearInterpolatedObjects(bool clearsubsteps);
156  /// Utility function used by getObjectAtTime() and getAffectorAtTime().
157  /// It finds the closest existing objects to the requested object.
158  void getBestObjects(const SIM_Object *object,
159  const SIM_Time &time,
160  bool allowinterpolation,
161  const SIM_Object *&matchobject,
162  SIM_Object *&nonconstmatchobject,
163  const SIM_Object *&bestbeforeobject,
164  SIM_Time &bestbeforetime,
165  const SIM_Object *&bestafterobject,
166  SIM_Time &bestaftertime);
167  /// Get the initial entry, which is the simulation state that shows
168  /// up for all times less then zero, and which is copied to be the
169  /// first timestep state when the cache is cleared.
170  SIM_CacheEntry *getInitialEntry();
171  /// Clears the initial entry.
172  void clearInitialEntry();
173  /// Get our current cache entry.
174  SIM_CacheEntry *getCurrentEntry() const;
175  /// Set our current cache entry.
176  void setCurrentEntry(SIM_CacheEntry *newentry);
177 
178  SIM_Engine *myEngine;
179  SIM_CacheOptions myCacheOptions;
180  UT_LinkList myCacheEntries;
181  SIM_CacheEntry *myCurrentEntry;
182  SIM_CacheEntry *myInitialEntry;
183  SIM_ObjectAtTimeMatrix myInterpolatedObjects;
184 
185  /// Do we have any temporary disk caches?
186  /// Does not count explicit entries.
187  /// We use this so we can determine if our getAllowSaveToDisk flag
188  /// needs to be enforced.
189  bool myHasDiskCache;
190 };
191 
192 #endif
193 
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.
GLenum src
Definition: glcorearb.h:1792