sprite-frame.md

Sprite Frame Assets

Sprite Frame is a container for UI rendering and basic graphics, which manages the clipping and tiling data on top of a Texture2D asset (by holding a reference to it).

Importing Sprite Frame Assets

Use the default asset import method to import image assets into the project, then set the type of image as sprite-frame in the Inspector panel:

Creator will then automatically create a spriteFrame resource under it as shown below:

Image assets will use thumbnails of their own pictures as icons in the Assets panel. When the image sub-asset is selected in the Assets panel, a thumbnail of the image is displayed below the Inspector panel.

The spriteFrame has the following properties:

Property	Description
Packable	Whether to participate in Dynamic Atlas and automatic atlas building processes.
Rotated	Read-only property, cannot be changed. Used to see if the sub-asset in the Texture Packer asset is rotated.
Offset X, Y	Read-only property, cannot be changed. Used to view the offset of the rectangle in Texture Packer asset.
Trim Type	Set the trim type, including: 1. Auto -- Automatic trim. For details, please refer to the Auto Trim for SpriteFrame documentation. 2. Custom -- Custom trim 3. None -- No trim, use original texture.
Trim Threshold	Set the transparency threshold, trim off the pixels whose transparency is below the set value. The default value is 1, and the range of values is 0~1. Only takes effect when Trim Type is set to Auto.
Trim X, Y, Width, Height	Sets the trim rect, only takes effect when Trim Type is set to Custom.
Border Top, Bottom, Left, Right	Set the texture margins of the 9-sliced, which can be edited visually by clicking on the Edit button below.

Using a Sprite Frame

The object contained in the container is using textures

In the editor, drag the SpriteFrame asset to the Sprite Frame property of the Sprite component to switch the image displayed by the Sprite. At runtime, taking the content picture in the above picture as an example, The entire asset is divided into image asset (content), its sub-asset (spriteFrame) and sub-asset (texture). The assets in the game package can be obtained by the following methods:

Method 1: (load ImageAsset):

const self = this;
const url = 'test_assets/test_altas/content';
resources.load(url, ImageAsset, (err: any, imageAsset) => {
  const sprite = this.getComponent(Sprite);
  const spriteFrame = new SpriteFrame();
  const tex = new Texture2D();
  tex.image = imageAsset;
  spriteFrame.texture = tex;
  sprite.spriteFrame = spriteFrame;
});

Method 2: (load SpriteFrame):

const self = this;
const url = 'test_assets/test_altas/content/spriteFrame';
resources.load(url, SpriteFrame, (err: any, spriteFrame) => {
  const sprite = this.getComponent(Sprite);
  sprite.spriteFrame = spriteFrame;
});

Assets on the server can only be loaded into ImageAsset. For specific methods, please refer to the dynamic load asset documentation.

Cocos Creator will provide a way to package an Image Asset as a SpriteFrame in a later release to make it easier for users to use image assets.

The container contains objects that are used by RenderTexture

RenderTexture is a rendering texture that renders content from the camera directly to a texture instead of the screen. SpriteFrame can easily display 3D camera content on the UI by managing RenderTexture. Example:

const cameraComp = this.getComponent(Camera);
const renderTexture = new RenderTexture();
const size = view.getVisibleSize();
renderTexture.reset({
   width: size.width,
   height: size.height,
   colorFormat: RenderTexture.PixelFormat.RGBA8888,
   depthStencilFormat: RenderTexture.DepthStencilFormat.DEPTH_24_STENCIL_8
});

cameraComp.targetTexture = renderTexture;
const spriteFrame = new SpriteFrame();
spriteFrame.texture = renderTexture;
const sprite = this.getComponent(Sprite);
sprite.spriteFrame = spriteFrame;

For API information, please refer to the SpriteFrame documentation.