SoCache(3)

💖 SoCache 💖

okay bestie, gather round, because today we're talking about SoCache — the superclass for all the internal cache classes in Coin. she's the mom of the cache world and she's iconic for it 👑

she lives in the library functions manual, and honestly? she's giving structure, she's giving organization, she's giving "I hold everything together." let's get into it 💅

---

✨ SYNOPSIS ✨

#include <Inventor/caches/SoCache.h>

Inherited by SoBoundingBoxCache, SoConvexDataCache, SoGLRenderCache, SoNormalCache, SoPrimitiveVertexCache, and SoTextureCoordinateCache. the whole girl squad fr fr 🫶

🌸 Public Member Functions

• SoCache (SoState *const state) — the constructor, she's born ✨
• void ref (void) — bump that reference count
• void unref (SoState *state=NULL) — drop that reference count
• void addElement (const SoElement *const elem) — add a dependency element
• virtual void addCacheDependency (const SoState *state, SoCache *cache) — link caches together
• virtual SbBool isValid (const SoState *state) const — vibe check on the cache
• const SoElement * getInvalidElement (const SoState *const state) const — who ruined the vibe?
• void invalidate (void) — force the cache to be invalid

🎀 Protected Member Functions

• virtual void destroy (SoState *state) — cleanup before deletion
• virtual ~SoCache () — the destructor, she's leaving 💔

---

🌈 Detailed Description 🌈

The SoCache class is the superclass for all internal cache classes.

She organizes reference counting so it's possible to share cache instances between everyone (sharing is caring, no cap 💖). She also organizes a list of elements that will affect the cache. and here's the tea: if any of those elements have changed since the cache was created, the cache is invalid. periodt.

🧚 the cache element test algorithm (iykyk)

The cache element test algorithm in Coin works like this:

1. Every element that is read before it's written when a cache is created gets stored in the SoCache's element list. This is done to detect when something outside the cache changes. 👀

Example: you have a SoCoordinate3 node outside an SoSeparator, but an SoIndexedFaceSet inside the 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.

2. At the next frame, the SoSeparator 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. sorry babe, she's expired 😭

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:

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

so let's break down this little ritual, because it's literally a sequence bestie, order matters:

• 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 🙈 (this is the part people forget, and then everything falls apart).
• 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.

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()). cute, right? 🎀

You don't have to manually add element dependencies. They will automatically be picked up when creating the cache. This is handled in SoElement::getConstElement(). she does the work so you don't have to 💅

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. do NOT do it early, that's the trap 🪤

---

🌟 Constructor & Destructor Documentation 🌟

💜 SoCache::SoCache (SoState *const state)

Constructor with state being the current state. hi bestie, welcome to the world ✨

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

Destructor. bye bestie, it was real 💔

---

🔥 Member Function Documentation 🔥

⭐ void SoCache::ref (void )

Increases the reference count by one. one more person showed up to the party 🎉

⭐ 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. so she gets a proper goodbye first 🥺

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

Adds elem to the list of elements this cache depends on. your new dependency, bestie 💅

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

Adds dependencies from cache to this cache. caches linking arms, we love to see it 🫶

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

Return TRUE if this cache is valid, FALSE otherwise. the ultimate vibe check 💖

Reimplemented in SoGLRenderCache.

⭐ 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 bacause of an element. (yes, that's "bacause" — I'm not fixing the typo, it's part of her charm 🎀)

⭐ void SoCache::invalidate (void )

Forces a cache to be invalid. sometimes you just gotta ✨

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

Can be overridden by subclasses to clean up before they are deleted. Default method does nothing. she's low maintenance like that.

Reimplemented in SoGLRenderCache.

---

👑 Author 👑

Generated automatically by Doxygen for Coin from the source code.

---

and that's the whole page bestie!! this was Coin Version 3.1.3, page SoCache(3), and she ate every single time 💅✨ no cap, fr fr. mwah 🫶💖