display.newImageRect()

类型 函数
库 display.*
返回值 DisplayObject（显示对象）
修订 版本 2024.3703
关键词 图像，对象，显示对象，图形
另请参阅 display.newImage()
display.loadRemoteImage()
显示对象 （指南）
图像表单 （指南）

概述

从文件中在屏幕上显示图像。此图像支持通过 object:setFillColor 进行着色。局部原点位于图像中心，并且 锚点 初始化为此局部原点。

此函数与 display.newImage() 的区别在于，display.newImageRect() 会自动替换更高分辨率的设备上的更高分辨率的资源，使此函数非常适合在不同分辨率的设备上显示图像。实际选择的图像将取决于 Corona 确定的当前内容缩放比例。这基于当前屏幕与在 config.lua 中定义的基本内容维度之间的比率。基于此，Corona 使用 imageSuffix 表（也在 config.lua 中定义），该表列出了同一系列图像的后缀，此函数从可用的图像选项中找到最佳匹配。随时可以通过只读属性 display.imageSuffix 访问所选后缀。有关更多信息，请参阅 项目配置 指南。

本质上，启用内容缩放时，应始终使用 display.newImageRect() 加载图像，并且此函数可以通过两种方式使用

  1. 使用针对目标设备设计的多个图像文件，并根据每个设备的分辨率/屏幕显示正确的图像。
  2. 调整高分辨率图像的大小以适合现有内容的宽度和高度。由于这仅使用一个高分辨率图像，因此它比方法 1 使用更多的纹理内存，但可以处理将在多个设备分辨率上使用的图像大小调整的情况。

语法

图像文件

display.newImageRect( [parent,] filename, [baseDir,] width, height )
parent （可选）

GroupObject（组对象）. 用于插入图像的可选显示组。

filename （必填）

String（字符串）. 要加载的图像文件的名称，相对于 baseDir（默认为 system.ResourceDirectory）。

baseDir （可选）

Constant（常量）. 指定 filename 所在的基本目录。选项包括 system.ResourceDirectory、system.DocumentsDirectory、system.ApplicationSupportDirectory、system.TemporaryDirectory 和 system.CachesDirectory。默认为 system.ResourceDirectory。

width （必填）

Number（数字）. 图像的内容宽度，即内容参考屏幕内的宽度。使用已打包到 ImageSheet（图像表单） 中的已修剪帧（例如通过 TexturePacker）时，请指定已*修剪*的宽度，而不是原始未裁剪帧的宽度。

height （必填）

Number（数字）. 图像的内容高度，即内容参考屏幕内的高度。使用已打包到 ImageSheet（图像表单） 中的已修剪帧（例如通过 TexturePacker）时，请指定已*修剪*的高度，而不是原始未裁剪帧的高度。

图像表单

display.newImageRect( [parent,] imageSheet, frameIndex, width, height )
parent （可选）

GroupObject（组对象）. 用于插入图像的可选显示组。默认情况下，如果未指定父级，则使用当前舞台（从 display.getCurrentStage() 返回）。

imageSheet （必填）

ImageSheet（图像表单）. 使用 graphics.newImageSheet() 创建的图像表单对象的引用。仅当您打算从图像表单创建对象时才需要此项。

frameIndex （必填）

Number（数字）. 表示从中创建对象的 ImageSheet（图像表单） 内的帧索引号。仅当指定了 imageSheet 时才需要此项。

width （必填）

Number（数字）. 图像的内容宽度，即内容参考屏幕内的宽度。使用已打包到 ImageSheet（图像表单） 中的已修剪帧（例如通过 TexturePacker）时，请指定已*修剪*的宽度，而不是原始未裁剪帧的宽度。

height （必填）

Number（数字）. 图像的内容高度，即内容参考屏幕内的高度。使用已打包到 ImageSheet（图像表单） 中的已修剪帧（例如通过 TexturePacker）时，请指定已*修剪*的高度，而不是原始未裁剪帧的高度。

纹理采样

默认情况下，新的图像表单将使用线性采样滤波器，以便在实际渲染区域大于或小于加载纹理的像素尺寸时，图像看起来更平滑。

您可以通过调用 display.setDefault() 更改默认纹理滤波器。首次加载图像后，将对同一文件的任何后续加载应用相同的采样滤波器。这是因为每个文件只加载一次纹理。

陷阱

图像指南

属性

（继承自 ShapeObject（形状对象） 和 display.newRect() 的属性）

示例

图像文件用法
local image = display.newImageRect( "image.png", 100, 100 )
image.x = display.contentCenterX
image.y = display.contentCenterY

-- Hide the object
image.isVisible = false

-- Remove it
image:removeSelf()
image = nil
图像表单用法
-- Create the image sheet object
local options =
{
    -- The params below are required
    width = 70,
    height = 41,
    numFrames = 2,

    -- The params below are optional (used for dynamic image selection)
    sheetContentWidth = 70,  -- width of original 1x size of entire sheet
    sheetContentHeight = 82  -- height of original 1x size of entire sheet
}
local imageSheet = graphics.newImageSheet( "fishies.png", options )

-- Create new image from the above image sheet
local obj = display.newImageRect( imageSheet, 1, 70, 41 )
obj.x, obj.y = 100, 100