类型 函数 库 graphics.* 返回值 图像图层 修订版 发行版 2024.3703 关键字 精灵图表、纹理图集、纹理内存、图像 另请参阅 图像图层 (指南)
图像图层 对象有时称为精灵图表或纹理图集，让你能够从单个图像文件中加载多幅图像。图像图层必须用于 动画精灵，还可以用来预加载许多静态图像。
默认情况下，新图像图层会使用线性采样滤镜，这样当实际渲染区域大于或小于已加载纹理的像素维度时，图像看起来就会平滑些。
你可以通过调用 display.setDefault() 来更改默认纹理滤镜。某一图像首次加载后，相同的采样滤镜将用于随后加载的同一文件。这是因为纹理是按文件加载一次的。
图像图层打包工具（如 TexturePacker）将输出 sourceX、sourceY、sourceWidth 和 sourceHeight 参数以获取修剪过的帧。在屏幕上显示这些帧时，图像将按照未修剪帧尺寸的中心点定位。
如果你想使用根据屏幕分辨率自动选择的动态图像图层，则必须包含 sheetContentWidth 和 sheetContentHeight 参数。详情请见下文。
在 Android 上，图像限制（缩小）为 2048×2048，即使设备上的最大纹理内存大小更大。原因是大多数 Android 设备没有足够的堆内存来加载图像。我们建议你不要加载大于 2048×2048 的图像文件。
graphics.newImageSheet( filename, [baseDir, ] options )
字符串. 这是包含图像图层所有帧的图像文件的文件名。此文件也称为“精灵图表”图像。
常量. 指定 filename 所在的基本目录。选项包括 system.ResourceDirectory、system.DocumentsDirectory、system.ApplicationSupportDirectory、system.TemporaryDirectory 和 system.CachesDirectory。默认值为 system.ResourceDirectory。
Table。带有代表结果图像表图片的特定选项的键的表——有关详细信息，请参阅下一节。
根据图像表图片的布局，options 表可以用两种方式进行配置
此配置假定图像表图片纹理中的所有帧共享相同的属性。
local options =
{
--required parameters
width = 50,
height = 50,
numFrames = 3,
--optional parameters; used for scaled content support
sheetContentWidth = 150, -- width of original 1x size of entire sheet
sheetContentHeight = 50 -- height of original 1x size of entire sheet
}
Number。图像表图片纹理中所有图片（帧）的宽度。
Number。图像表图片纹理中所有图片（帧）的高度。
Number。图像表图片中图片（帧）的总数。
Number。每个帧周围的边框，通常用于其边缘被挤压以消除重缝痕迹的瓦片。默认值为 0。当大于 0 时，将覆盖用于裁剪帧的裁剪选项。
这些值告诉 Solar2D 原始 1x 图像表图片的大小。举例来说，如果你正在为 iPad 和 iPad Retina 开发，并且你正在为常规 iPad 使用 1000×1000 的图像表图片，那么你应该为此两个值指定 1000，然后以 2000×2000 来设计你的 Retina 图像表图片。有关此主题的更多信息，请参阅 项目配置 指南。
如果图像表图片有不同大小的帧，则需要此配置。在这种情况下，options 包含父 frames 表内的表数组，并且这些表中的每个表都代表图像表图片中的单个帧。
local options =
{
--array of tables representing each frame (required)
frames =
{
-- Frame 1
{
--all parameters below are required for each frame
x = 2,
y = 70,
width = 50,
height = 50
},
-- Frame 2
{
x = 2,
y = 242,
width = 50,
height = 52
},
-- Frame 3 and so on...
},
-- Optional parameters; used for scaled content support
sheetContentWidth = 1024,
sheetContentHeight = 1024
}
Number。纹理中帧的 x 位置。
Number。纹理中帧的 y 位置。
Number。帧的宽度；如果裁剪，请在此处指定裁剪后的宽度。
Number。帧的高度；如果裁剪，请在此处指定裁剪后的高度。
Number。原始未裁剪帧的宽度。默认值与 width 相同。
Number。原始未裁剪帧的高度。默认值与 height 相同。
Number。相对于未裁剪图片的裁剪矩形的 x 原点。默认值为 0。
Number。相对于未裁剪图片的裁剪矩形的 y 原点。默认值为 0。
Number。每个单独帧周围的像素量。这对缩放图像表图片非常必要，因为这样可以消除边缘周围的混合痕迹。默认值为 0。
这些值告诉 Solar2D 原始 1x 图像表图片的大小。举例来说，如果你正在为 iPad 和 iPad Retina 开发，并且你正在为常规 iPad 使用 1000×1000 的图像表图片，那么你应该为此两个值指定 1000，然后以 2000×2000 来设计你的 Retina 图像表图片。有关此主题的更多信息，请参阅 项目配置 指南。
local options =
{
-- Required parameters
width = 70,
height = 41,
numFrames = 2,
-- Optional parameters; used for scaled content support
sheetContentWidth = 70, -- width of original 1x size of entire sheet
sheetContentHeight = 82 -- height of original 1x size of entire sheet
}
local imageSheet = graphics.newImageSheet( "characterSheet.png", options )
local options =
{
-- Array of tables representing each frame (required)
frames =
{
-- Frame 1
{
x = 2,
y = 70,
width = 50,
height = 50
},
-- Frame 2
{
x = 2,
y = 242,
width = 50,
height = 52
},
},
-- Optional parameters; used for scaled content support
sheetContentWidth = 1024,
sheetContentHeight = 1024
}
local imageSheet = graphics.newImageSheet( "characterSheet.png", options )