display.captureBounds()

Android

当应用暂停时，Android 操作系统会从内存中移除所有 OpenGL 纹理。当应用恢复时，Corona 必须重新加载所有图像，但捕获的图像不再存在于内存中。如果您需要在 Android 中恢复捕获的图像，可以使用以下解决方案：

• 通过 display.save() 函数将返回的捕获图像保存到文件。请注意，您不能在 Android 的 "applicationSuspend" 和 "applicationExit" 事件 中使用 display.save() 函数，因为内存中没有 OpenGL 纹理可供保存。
• 使用捕获对象的边界，通过 display.newImageRect() 显示保存到文件的图像。

此外，如果您将 saveToPhotoLibrary 选项 设置为 true，则必须在 build.settings 文件中设置以下权限：

settings =
{
    android =
    {
        usesPermissions =
        {
            "android.permission.WRITE_EXTERNAL_STORAGE",
        },
    },
}

iOS

在 iOS 上，如果您将 saveToPhotoLibrary 选项 包含为 true，则必须在 build.settings 的 plist 表中包含以下键/描述。当系统提示用户允许访问时，相关的描述将作为警报的一部分显示。请注意，您可以根据自己的喜好自定义这些描述，甚至可以对其进行本地化（指南）。

settings =
{
    iphone =
    {
        plist =
        {
            NSPhotoLibraryUsageDescription = "This app would like to access the photo library.",
            NSPhotoLibraryAddUsageDescription = "This app would like to add the photo library.",
        },
    },
}

macOS

将屏幕截图图像保存为 JPEG 文件到当前用户的“图片”文件夹中。

请注意，如果您计划将应用程序提交到 Mac App Store，它将被**沙盒化**。这意味着必须请求在“图片”文件夹中读取/写入文件的特殊权限。为此，只需在settings → osxbuild.settings 表中添加 entitlements 条目，如下所示。有关更多详细信息，请参阅 Apple 的 文档。

settings = 
{
    osx = {
        entitlements = {
            ["com.apple.security.assets.pictures.read-write"] = true,
        },
    },
}

Windows

将屏幕截图图像保存为 PNG 文件到用户的我的图片目录下的以 Corona 应用命名的子目录中。对于 Corona 模拟器，此目录将是我的图片\Corona Simulator。对于Corona 构建的桌面应用程序，此目录将是我的图片\<AppName>.

启动时捕获

如果您需要在应用程序启动时捕获显示对象，例如在执行 `main.lua` 初始化应用程序时，则必须在 timer.performWithDelay() 调用中调用 `display.captureBounds()`。建议延迟至少 100 毫秒。

local function captureWithDelay()
    local screenBounds =
    {
        xMin = 0,
        xMax = 100,
        yMin = 0,
        yMax = 100,
    }
    local capture = display.captureBounds( screenBounds )
end

timer.performWithDelay( 100, captureWithDelay )

screenBounds _{^（必填）}

表 (Table)。 将要捕获的屏幕部分指定为一个矩形，其边界采用内容坐标。此表必须包含以下属性，否则将发生错误。

local screenBounds =
{
    xMin = 0,
    xMax = 100,
    yMin = 0,
    yMax = 100
}

您还可以传入 object.contentBounds 属性返回的边界表，这将捕获该对象及其背后的所有内容。

请注意，此捕获函数只能捕获屏幕上显示的内容。如果此边界表中的坐标超出了屏幕边界，则生成的捕获图像将被裁剪到屏幕边界。如果边界表完全位于屏幕之外，则此函数将不执行任何操作并返回 `nil`。

saveToPhotoLibrary _{^（可选）}

布尔值 (Boolean)。 如果为 `true`，则将图像添加到设备的照片库中。对于 Android 和 iOS 设备，这也需要满足注意事项中列出的要求。

捕获右下象限

-- Set up a bounds table for capturing the bottom-right quadrant of the screen
local screenBounds =
{
    xMin = display.contentWidth / 2,
    xMax = display.contentWidth,
    yMin = display.contentHeight / 2,
    yMax = display.contentHeight
}

-- Capture the bounds of the screen
local myCaptureImage = display.captureBounds( screenBounds )

捕获显示对象边界

-- Display a circle at the center of the screen
local myCircle = display.newCircle( 0, 0, 50 )
myCircle.x = display.contentWidth / 2
myCircle.y = display.contentHeight / 2

-- Capture the above circle object
local myCaptureImage = display.captureBounds( myCircle.contentBounds )

将捕获内容写入照片库

-- Capture the entire stage, minus the letterbox area
-- To save to the photo library, you must set the second argument to true
local myCaptureImage = display.captureBounds( display.currentStage.contentBounds, true )

-- Remove the returned capture image since we're only interested in saving to the photo library
-- Doing this immediately after the above function call prevents it from being drawn on screen
myCaptureImage:removeSelf()
myCaptureImage = nil