SoCache(3)

🎀 NAME 🎀

SoCache — bestie, this is the superclass for all the internal cache classes. The mother of caches. The blueprint. 💅

---

✨ SYNOPSIS ✨

#include <Inventor/caches/SoCache.h>

Inherited by SoBoundingBoxCache, SoConvexDataCache, SoGLRenderCache, SoNormalCache, SoPrimitiveVertexCache, and SoTextureCoordinateCache. It's giving very "everyone wants to be me" energy. 👑

💅 Public Member Functions

• SoCache (SoState *const state) — constructor, takes the current state, more on that below.
• void ref (void) — bumps the reference count up by one.
• void unref (SoState *state=NULL) — drops the reference count by one, and when it hits zero the cache gets yeeted (deleted).
• void addElement (const SoElement *const elem) — adds elem to the list of elements this cache depends on.
• virtual void addCacheDependency (const SoState *state, SoCache *cache) — adds dependencies from cache to this cache.
• virtual SbBool isValid (const SoState *state) const — TRUE if the cache is valid, FALSE otherwise.
• const SoElement * getInvalidElement (const SoState *const state) const — hands you the element that caused the invalidation.
• void invalidate (void) — forces the cache to be invalid, no take-backs.

🫶 Protected Member Functions

• virtual void destroy (SoState *state) — subclasses can override this to clean up before deletion. Default does nothing (iconic minimalist behaviour).
• virtual ~SoCache () — the destructor. 🪦

---

🌸 Detailed Description 🌸

So the SoCache class is the superclass for all the internal cache classes. Periodt.

It handles reference counting so multiple things can share the same cache instance (sharing is caring, fr). It also keeps a whole list of elements that affect the cache — and bestie, if any of those elements have changed since the cache was born, that cache is invalid. Done. Over. 💀

The cache element test algorithm in Coin goes like this:

Every element that gets read before it gets written when a cache is created is stored in the SoCache's element list. Why? To detect when something outside the cache changes. iykyk.

Example: imagine you have an SoCoordinate3 node outside an SoSeparator, but an SoIndexedFaceSet inside that SoSeparator. If the SoSeparator creates a cache, SoIndexedFaceSet will read SoCoordinateElement, and since SoCoordinateElement hasn't been set after the cache was opened, the cache stores that element in the cache's list of element dependencies. Sneaky but smart.

Next frame, the SoSeparator will test if the cache is valid, and will then test all the dependency elements. If even one of the elements doesn't match, the cache is not valid and can't be used. RIP cache. 😭

That's the basics. But there are some steps you have to do when creating a cache to make the cache dependencies actually work. Basically you have to do it like this:

SbBool storedinvalid = SoCacheElement::setInvalid(FALSE);
state->push();
SoMyCache * cache = new SoMyCache(state);
cache->ref();
SoCacheElement::set(state, cache);
buildMyCache();
state->pop();
SoCacheElement::setInvalid(storedinvalid);

First you reset and store the old value of the cache invalid-flag. Then you push the state so the cache can detect when something outside the cache is changed (and so it's able to change the cache element). Next, you create the cache — and do not forget to ref it, that part matters. Finally, set the current cache in the cache element and build the cache. After building it, you pop the state and restore the invalid-cache flag. Slay, that's the whole ritual. ✨

When building the cache, all elements that are read will be copied into the cache (using SoElement::copyMatchInfo()), and these copied elements are used to test the validity of the cache (in SoCache::isValid()).

You don't have to manually add element dependencies, bestie — they will automatically be picked up when creating the cache. This is handled in SoElement::getConstElement().

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 SoCache::invalidate() whenever the notify()-method for your node is called. See for instance SoShape::notify().

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. Trust the process. 🫶

---

🧚 Constructor & Destructor Documentation 🧚

SoCache::SoCache (SoState *const state)

Constructor, with state being the current state. Simple as that.

SoCache::~SoCache () [protected], [virtual]

Destructor. 🪦

---

🔥 Member Function Documentation 🔥

void SoCache::ref (void )

Increases the reference count by one. ✨

void SoCache::unref (SoState * state = NULL)

Decreases the reference count by one. When the reference count reaches zero, the cache is deleted. The SoCache::destroy() method is called before the destructor is called. Order matters, bestie. 💅

void SoCache::addElement (const SoElement *const elem)

Adds elem to the list of elements this cache depends on.

void SoCache::addCacheDependency (const SoState * state, SoCache * cache) [virtual]

Adds dependencies from cache to this cache.

SbBool SoCache::isValid (const SoState * state) const [virtual]

Return TRUE if this cache is valid, FALSE otherwise.

Reimplemented in SoGLRenderCache, and SoPrimitiveVertexCache.

const SoElement * SoCache::getInvalidElement (const SoState *const state) const

Returns the element that caused the invalidation. Returns NULL if the cache is valid, or if the cache was not invalidated because of an element. So if you get NULL, either everything's fine or the drama came from somewhere else. 🤷♀️

void SoCache::invalidate (void )

Forces a cache to be invalid.

void SoCache::destroy (SoState * state) [protected], [virtual]

Can be overridden by subclasses to clean up before they are deleted. Default method does nothing.

Reimplemented in SoGLRenderCache.

---

💜 Author 💜

Generated automatically by Doxygen for Coin from the source code. Not me writing it by hand, the robots did it. 🤖

---

And that's the whole page, bestie — SoCache(3) from Coin, version 4.0.10, dated Thu Jun 25 2026 00:00:00. Thanks for reading all the way to the bottom, you're literally the main character. 🎀✨💖