# Atlas导出文件格式

本页描述了基于libgdx图集格式的Spine [纹理图集(texture atlas)](/spine-texture-packer#Texture-atlas-files)格式. [Spine 运行时](/spine-runtimes)将加载这些数据以绘制动画.

Spine 运行时能处理和加载atlas数据. 你无需自己编写加载代码, 除非你准备从零开始打造你自己的运行时(这工作量浩瀚无涯).

该格式是一种基于行的简单文本格式, 由一个或多个页(page)条目组成, 每个条目又可包含任意数量的区域(region)条目. 页面条目由一个空行分隔. 除了换行符外可在文件中任意留白. 这是一个包含两个页的atlas文件示例:

```
page1.png
	size: 640, 480
	format: RGBA8888
	filter: Linear, Linear
	repeat: none
	pma: true
dagger
	bounds: 372, 100, 26, 108
head
	index: 0
	bounds: 2, 21, 103, 81
	rotate: 90

page2.png
	size: 640, 480
	format: RGB565
	filter: Nearest, Nearest
	repeat: x
bg-dialog
	index: -1
	rotate: false
	bounds: 519, 223, 17, 38
	offsets: 2, 2, 21, 42
	split: 10, 10, 29, 10
	pad: -1, -1, 28, 10

```

# 页(Page)块

页块包含了页图像名称, 以及加载和渲染图像的相关信息. 下面是一个页块的示例:

```
page1.png
	size: 640, 480
	format: RGBA8888
	filter: Linear, Linear
	repeat: none
	pma: true
```

**Page属性:**
* **name:** 首行为该页中的图像名称. 图片位置由atlas加载器来查找, 通常是再atlas文件的同目录下.
* **size:** 页中图像的宽度和高度. 在加载图像之前告知atlas加载器是非常有必要的, 例如, 可以提前为其分配缓冲区. 若省略则默认为`0,0`.
* **format:** atlas加载器在内存中存储图像时应使用的格式. Atlas加载器可忽略该属性, 其可用值为: `Alpha`、`Intensity`、`LuminanceAlpha`、`RGB565`、`RGBA4444`、`RGB888`或`RGBA8888`. 若省略则默认为`RGBA8888`.
* **filter:** Texture过滤器的缩略和放大方式. Atlas加载器可忽略该属性. 其可用值为: `Nearest`, `Linear`, `MipMap`, `MipMapNearestNearest`, `MipMapLinearNearest`, `MipMapNearestLinear`, 或`MipMapLinearLinear`. 若省略则默认为`Nearest`.
* **repeat:** Texture包裹设置. Atlas加载器可忽略该属性. 其可用值为: `x`, `y`, `xy`, 或 `none`. 若省略则默认为`none`.
* **pma:** 若值为`true`则表示图像使用了premultiplied alpha. 若省略则默认为`false`.

# 区域(Region)块

区域块包含了页图像中的区域位置以及该区域的其他信息. 下面是一个区域块的示例:

```
bg-dialog
	index: -1
	rotate: false
	bounds: 519, 223, 17, 38
	offsets: 2, 2, 21, 42
	split: 10, 10, 29, 10
	pad: -1, -1, 28, 10
```

**Region属性:**
* **name:** 首行为区域名称, 用于在atlas中定位一个区域. 多个区域若**索引(index)**各不相同, 则它们可以同名.
* **index:** 索引可以打包许多同名图像, 只要每个图像索引不同即可. 通常情况下, 索引是区域的帧号, 这些区域在逐帧动画中会依序绘制. 若省略则默认为`-1`.
* **bounds:** 该图像在页图像中的像素位置x和y, 以及打包后图像尺寸, 即该图像在页图像中的像素尺寸. 若省略则默认为`0,0,0,0`.
* **offsets:** 在打包前, 要从图像的左侧和底部边缘去除的空白像素值, 以及原始图像尺寸(此图像在打包前的像素尺寸). 如果进行了去除操作, 则打包后的图像尺寸可能会小于原始图像. 若省略则左侧和底部像素偏移默认为`0,0`, 原始图像尺寸等于打包后的图像尺寸.
* **rotate:** 若为`true`, 则表示该区域被逆时针旋转90度后存储在页图像中; 若为`false`则表示没有旋转. 属性值也可直接填入旋转角度(范围是0至360度). 若省略则默认为`0`.
* **split:** 对图像进行九宫格分割, 属性值是从原图边缘算起的像素值. 分割所定义的3x3的网格, 可以在缩放图像时不用拉伸图像的所有部分. 若省略则默认为`null`.
* **pad:** 九宫格分割后四周的填充厚度, 属性值是从原图边缘算起的像素值. 填充可以把置于九宫格中的内容以不同的方式嵌入到分片中. 若省略则默认为`null`.

区域块后的空行表示一个页区域的结束. 再跟一行则表示另一个页块或整个文件的结尾.

## 名/值对

除上述方式外, 区域的属性值还能以名/值对的形式存储. 这可以将额外的数据附加到各个区域上. Spine用这种方法在输出逐帧动画的图像时, 存储每个区域的原点(相对于世界位置`0,0`的偏移量)和骨骼位置.

# 渲染

当渲染atlas中的某个区域时, 必须特别注意创建atlas的texture打包设置. 这些设置可以更高效地对texture打包, 但为了简化渲染, 也可以在创建atlas时禁用这些设置. .

## 旋转

如果存储在atlas中的区域经过了旋转, 渲染时需要通过调整UV来还原旋转前的图像.

## 空白剔除(Whitespace stripping)

如果区域在打包前去除了边缘的空白, 那么渲染时就需要调整绘制位置, 使其看起来好像没有去掉过空白部分.

如果一个区域在绘制时可能有翻转操作, 那么在渲染翻转的区域时必须要考虑空白剔除的问题.

若要从右侧和上缘去除空白则可以这样计算:
```
offsetRight = originalWidth - packedWidth - offsetLeft
offsetTop = originalHeight - packedHeight - offsetBottom
```