Developers Manual > Cocos2d-x > Modules > Memory Management > Texture Cache

Texture Cache

version: Cocos2d-x v3.x
update: Updated almost 3 years ago


Textures are cached to be drawn later. The size, color, and texture region for each cached image cannot be modified. This information is stored in memory and does not have to be sent to GPU every time when it is drawn.


Cocos2d-x uses a texture cache that persists Sprite by invoke TextureCache or SpriteFrameCache. You can preload textures into cache and they will still be available from your scene. How you load these are up to you. For example, you can opt to do it asynchronously, to allow your loading scene to maintain a decent frame rate and render a progress bar.

When you create a sprite, you normally use Sprite::create(fileName) . If you look to the code of Sprite::create(fileName) method, you will find that it adds image to the texture cache:

    bool Sprite::initWithFile(const std::string& filename)
        CCASSERT(filename.size()>0, "Invalid filename for sprite");
        auto texture = Director::getInstance()->getTextureCache()->addImage(filename);

        if (texture)
            Rect rect = Rect::ZERO;
            rect.size = texture->getContentSize();
            return initWithTexture(texture, rect);

        // don't release here.
        // when load texture failed, it's better to get a "transparent" sprite then a crashed program
        // this->release(); 
        return false;

Singleton that handles the loading of textures. Once the texture is loaded, the next time it will return a reference of the previously loaded texture.


SpriteFrameCache is a cache of all sprite frames. Using a spritesheet and its associated xml file we can load multiple sprites into the cache. From here we can create Sprite objects with sprites from the cache.

Texture is basically a large image that contains lots of smaller textures. Following is an example:

There are 3 ways to load a texture with SpriteFrameCache:

  • a xml(plist) filename
  • a xml(plist) filename and a texture
  • a SpriteFrame and a sprite frame name


    auto cache = SpriteFrameCache::getInstance();

    cache->addSpriteFramesWithFile("family.plist", "family.png");


    local cache = cc.SpriteFrameCache:getInstance()

    cache:addSpriteFrames("animations/grossini_gray.plist", "animations/grossini_gray.png")

The reason why atlas sprites help with memory is because every time you want to create a new sprite with an image exactly the same as another one, you just grab that atlas manager image, tell it where you want to grab your image file from, and it re-uses that memory instead of creating an entire new image in memory.

SpriteFrameCache vs. SpriteBatchNode vs. Modern renderer

a) We rewrote the renderer from scratch. The Render graph was decoupled from the Scene graph. That means that auto-batching is supported, finally :-) And the new renderer is so fast, that we no longer encourage the use of SpriteBatchNode.

b) The SpriteBatchNode renders all of its children in one go, in one batched draw call. That’s why you need to add sprites to the batch node so it can render them all together. Only sprites using the same texture as the batch node can be added to a batch node, because you can only batch draw from the same texture. Whenever the engine has to switch from one texture to another, it issues a new draw call.

b1) You can’t do this because the batch node renders its children. If you add the sprites to any other node, each sprite draws itself, which means one additional draw call per sprite. And the sprite batch node has nothing to do.

c) The SpriteBatchNode is just a regular node. You can remove it from the scene like any other node. The texture and sprite frames are cached in the TextureCache and SpriteFrameCache singleton classes. If you want to remove the textures and sprite frames from memory, you have to do it through the cache classes.


This topic only works with Sprite objects but the general principle applies for all kinds of assets for which cocos2d has a cache (textures, sprite frames, animations and pre-loaded sound effects). Most other assets without a “cache” can simply be reloaded or updated.

grossini_family.png (7.2 kB) iven, 2013-01-24 06:15

Sign up for our newsletter to keep up with the latest developments, releases and updates for Cocos2d-x.