---
name: "SoCache"
section: "3"
platform: "linux"
package: "coin"
version: "1:4.0.10-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/SoCache"
---

# SoCache(3)

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

## NAME

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

## SYNOPSIS

\#include \<Inventor/caches/SoCache.h\>

Inherited by **SoBoundingBoxCache**, **SoConvexDataCache**, **SoGLRenderCache**, **SoNormalCache**, **SoPrimitiveVertexCache**, and **SoTextureCoordinateCache**.

### Public Member Functions

**SoCache** (**SoState** \*const state)\
 void **ref** (void)\
 void **unref** (**SoState** \*state=NULL)\
 void **addElement** (const **SoElement** \*const elem)\
 virtual void **addCacheDependency** (const **SoState** \*state, **SoCache** \*cache)\
 virtual SbBool **isValid** (const **SoState** \*state) const\
 const **SoElement** \* **getInvalidElement** (const **SoState** \*const state) const\
 void **invalidate** (void)\

### Protected Member Functions

virtual void **destroy** (**SoState** \*state)\
 virtual **~SoCache** ()\

## Detailed Description

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

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:

Every element that is read before it is written when a cache is created is 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.

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.

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);
```

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.

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. 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.

## Constructor & Destructor Documentation

### SoCache::SoCache (SoState \*const state)

Constructor with *state* being the current state.

### 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.

### 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.

### 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.