.TH "SoCache" 3 "Sat Oct 12 2013" "Version 4.0.0a" "Coin" \" -*- nroff -*- .ad l .nh .SH NAME SoCache \- .PP The \fBSoCache\fP class is the superclass for all internal cache classes\&. .PP It organizes reference counting to make it possible to share cache instances\&. It also organizes a list of elements that will affect the cache\&. If any of the elements have changed since the cache was created, the cache is invalid\&. .SH SYNOPSIS .br .PP .PP \fC#include \fP .PP Inherited by \fBSoBoundingBoxCache\fP, \fBSoConvexDataCache\fP, \fBSoGLRenderCache\fP, \fBSoNormalCache\fP, \fBSoPrimitiveVertexCache\fP, and \fBSoTextureCoordinateCache\fP\&. .SS "Public Member Functions" .in +1c .ti -1c .RI "\fBSoCache\fP (\fBSoState\fP *const state)" .br .ti -1c .RI "void \fBref\fP (void)" .br .ti -1c .RI "void \fBunref\fP (\fBSoState\fP *state=NULL)" .br .ti -1c .RI "void \fBaddElement\fP (const \fBSoElement\fP *const elem)" .br .ti -1c .RI "virtual void \fBaddCacheDependency\fP (const \fBSoState\fP *state, \fBSoCache\fP *cache)" .br .ti -1c .RI "virtual SbBool \fBisValid\fP (const \fBSoState\fP *state) const " .br .ti -1c .RI "const \fBSoElement\fP * \fBgetInvalidElement\fP (const \fBSoState\fP *const state) const " .br .ti -1c .RI "void \fBinvalidate\fP (void)" .br .in -1c .SS "Protected Member Functions" .in +1c .ti -1c .RI "virtual void \fBdestroy\fP (\fBSoState\fP *state)" .br .ti -1c .RI "virtual \fB~SoCache\fP ()" .br .in -1c .SH "Detailed Description" .PP The \fBSoCache\fP class is the superclass for all internal cache classes\&. .PP It organizes reference counting to make it possible to share cache instances\&. It also organizes a list of elements that will affect the cache\&. If any of the elements have changed since the cache was created, the cache is invalid\&. The cache element test algorithm in Coin works like this: .PP Every element that is read before it's written when a cache is created is stored in the \fBSoCache\fP's element list\&. This is done to detect when something outside the cache changes\&. .PP Example: you have a \fBSoCoordinate3\fP node outside an \fBSoSeparator\fP, but an \fBSoIndexedFaceSet\fP inside the \fBSoSeparator\fP\&. If the \fBSoSeparator\fP creates a cache, \fBSoIndexedFaceSet\fP will read \fBSoCoordinateElement\fP, and since \fBSoCoordinateElement\fP hasn't been set after the cache was opened, the cache stores that element in the cache's list of element dependencies\&. .PP At the next frame, the \fBSoSeparator\fP will test if the cache is valid, and will then test all dependency elements\&. If one of the elements doesn't match, the cache is not valid and can't be used\&. .PP That's the basics\&. There are some steps you have to do when creating a cache to make the cache dependencies work\&. Basically you have to do it like this: .PP .PP .nf SbBool storedinvalid = SoCacheElement::setInvalid(FALSE); state->push(); SoMyCache * cache = new SoMyCache(state); cache->ref(); SoCacheElement::set(state, cache); buildMyCache(); state->pop(); SoCacheElement::setInvalid(storedinvalid); .fi .PP .PP First you reset and store the old value of the cache invalid-flag\&. Then you push the state so that the cache can detect when something outside the cache is changed (and to be able to change the cache element)\&. Next, you create the cache - don't forget to ref it\&. Finally, set the current cache in the cache element and build the cache\&. After building the cache, you pop the state and restore the invalid-cache flag\&. .PP When building the cache, all elements that are read will be copied into the cache (using \fBSoElement::copyMatchInfo()\fP), and these copied elements are used to test the validity of the cache (in \fBSoCache::isValid()\fP)\&. .PP You don't have to manually add element dependencies\&. They will automatically be picked up when creating the cache\&. This is handled in \fBSoElement::getConstElement()\fP\&. .PP If you want the cache to be invalidated when some field inside your node is changed, it's common to overload the notify()-method, and call \fBSoCache::invalidate()\fP whenever the notify()-method for your node is called\&. See for instance \fBSoShape::notify()\fP\&. .PP Also, don't delete the cache in your notify() method\&. Wait until the next time the cache is needed before unref-ing the old cache\&. .SH "Constructor & Destructor Documentation" .PP .SS "SoCache::SoCache (\fBSoState\fP *conststate)" Constructor with \fIstate\fP being the current state\&. .SS "SoCache::~SoCache ()\fC [protected]\fP, \fC [virtual]\fP" Destructor .SH "Member Function Documentation" .PP .SS "void SoCache::ref (void)" Increases the reference count by one\&. .SS "void SoCache::unref (\fBSoState\fP *state = \fCNULL\fP)" Decreases the reference count by one\&. When the reference count reaches zero, the cache is deleted\&. The \fBSoCache::destroy()\fP method is called before the destructor is called\&. .SS "void SoCache::addElement (const \fBSoElement\fP *constelem)" Adds \fIelem\fP to the list of elements this cache depends on\&. .SS "void SoCache::addCacheDependency (const \fBSoState\fP *state, \fBSoCache\fP *cache)\fC [virtual]\fP" Adds dependencies from \fIcache\fP to this cache\&. .SS "SbBool SoCache::isValid (const \fBSoState\fP *state) const\fC [virtual]\fP" Return \fITRUE\fP if this cache is valid, \fIFALSE\fP otherwise\&. .PP Reimplemented in \fBSoPrimitiveVertexCache\fP, and \fBSoGLRenderCache\fP\&. .SS "const \fBSoElement\fP * SoCache::getInvalidElement (const \fBSoState\fP *conststate) const" Returns the element that caused the invalidation\&. Returns \fINULL\fP if the cache is valid, or if the cache was not invalidated bacause of an element\&. .SS "void SoCache::invalidate (void)" Forces a cache to be invalid\&. .SS "void SoCache::destroy (\fBSoState\fP *state)\fC [protected]\fP, \fC [virtual]\fP" Can be overridden by subclasses to clean up before they are deleted\&. Default method does nothing\&. .PP Reimplemented in \fBSoGLRenderCache\fP\&. .SH "Author" .PP Generated automatically by Doxygen for Coin from the source code\&.