Overview

Creates a TextureResource object which allows you to access and manage textures. This can be used to pre-load a texture/image and prevent it from being disposed when there is no display object using it.

There are several important nuances you should understand before using TextureResource objects — see the next section for details.

Gotchas

TextureResource objects created with graphics.newTexture() will not be automatically disposed/released, even if there are no display objects using the texture. This can lead to memory leaks, so you should handle this task manually. Individually, texture resource objects can be disposed/released via texture:releaseSelf(), or in a wider scope, graphics.releaseTextures() can be used to release all texture objects sharing the same type property.

TextureResource objects have filename and baseDir properties which can be used to refer to the underlying texture. These texture-related properties should not be used to reference the same file or directory constant in non-texture-related methods — for example, if you specify "background.png" as the filename for the texture, do not attempt to use texture.filename as a reference to the same file in system.pathForFile(). Essentially, these properties refer to internal memory, not the file system.

If you don't need to maintain reference to a TextureResource object, it is recommended that you dispose/release it. If any display objects are currently using the released texture, they will not be corrupted — instead, they will hold on to the texture under the hood, and if/when they are removed, the texture will be automatically disposed.

Calling graphics.newTexture() multiple times with reference to the same file will not create unique TextureResource objects. Thus, if you call texture:releaseSelf() on any texture resource object, it will be disposed/removed from memory, and all other pointers to graphics.newTexture() which used the same file will become nil.

Syntax

graphics.newTexture( params )

params (required)

Table. Table containing the required parameters for the TextureResource object — see the next section for details.

Parameter Reference

type (required)

String. The type of the texture to be created. Depending on this value, other key-value parameters will be taken into account (inspect carefully below).

"image" — Creates a TextureResource object of type TextureResourceBitmap. Objects of this type are used to pre-load and cache textures based on real images within the project's file system.

filename (required)

String. Only applies when type is "image". Indicates the name of the image file to load, relative to baseDir (system.ResourceDirectory by default).

baseDir (optional)

Constant. Only applies when type is "image". Specifies the base directory where filename is located. Options include system.ResourceDirectory, system.DocumentsDirectory, system.ApplicationSupportDirectory, system.TemporaryDirectory and system.CachesDirectory. Default is system.ResourceDirectory.