Android 图像解码器

AImageDecoder 函数结果代码。

在 API 30 中引入。

许多函数会返回此值来指示成功 (ANDROID_IMAGE_DECODER_SUCCESS) 或失败原因。失败时，任何输出参数都应被视为未初始化，除非另有说明。使用 AImageDecoder_resultToString 获取结果代码的可读版本。

在显示下一帧之前，如何“处置”当前帧。

在 API 31 中引入。

这个信息，以及 AImageDecoderFrameInfo 中的其他信息，对于确定帧是否独立很有用，但解码器会处理帧的处置，因此简单的顺序客户端不需要这个。

当前帧与上一帧的混合方式。

在 API 31 中引入。

这个信息，以及 AImageDecoderFrameInfo 中的其他信息，对于确定帧是否独立很有用，但解码器会处理帧的混合，因此简单的顺序客户端不需要这个。

用于解码图像的不透明句柄。

在 API 30 中引入

使用以下方法之一创建

• AImageDecoder_createFromAAsset
• AImageDecoder_createFromFd
• AImageDecoder_createFromBuffer

创建后，可以使用 AImageDecoder_getHeaderInfo 检索编码图像的信息。其他函数，如 AImageDecoder_setTargetSize，可用于指定如何解码，而 AImageDecoder_decodeImage 会解码到客户端提供的内存中。

AImageDecoder 对象不是线程安全的，不应跨线程共享。

包含关于单个帧的动画信息的不透明句柄。

在 API 31 中引入

持续时间（使用 AImageDecoderFrameInfo_getDuration 检索）对于客户端以正确的速度显示动画是必要的。对于想要确定哪些帧是独立的（或它们依赖于哪些帧）的客户端来说，其他信息很有帮助，但对于想要按顺序显示所有帧的简单客户端来说则不必要。

表示关于编码图像信息的不透明句柄。

在 API 30 中引入

使用 AImageDecoder_getHeaderInfo 检索，并传递给 AImageDecoderHeaderInfo_getWidth 和 AImageDecoderHeaderInfo_getHeight 等方法。

创建一个未初始化的 AImageDecoderFrameInfo。

在 API 31 中引入。

这可以传递给 AImageDecoder_getFrameInfo，以填充有关当前帧的信息。它可以重复使用。

必须使用 AImageDecoderFrameInfo_delete 删除。

删除 AImageDecoderFrameInfo。

在 API 31 中引入。

返回此帧与上一帧的混合方式。

在 API 31 中引入。

这个信息，以及 AImageDecoderFrameInfo 中的其他信息，对于确定帧是否独立很有用，但解码器会处理帧的混合，因此简单的顺序客户端不需要这个。

返回此帧在显示下一帧之前如何“处置”。

在 API 31 中引入。

这个信息，以及 AImageDecoderFrameInfo 中的其他信息，对于确定帧是否独立很有用，但解码器会处理帧的处置，因此简单的顺序客户端不需要这个。

报告显示当前帧的纳秒数。

在 API 31 中引入。

错误

• 如果 |info| 为 null，则返回 ANDROID_IMAGE_DECODER_BAD_PARAMETER。

此帧更新的图像矩形（范围为 0, 0, AImageDecoderHeaderInfo_getWidth, AImageDecoderHeaderInfo_getHeight）。

在 API 31 中引入。

请注意，这不受 AImageDecoder_setTargetSize 或 AImageDecoder_setCrop 调用的影响。

帧可能仅更新图像的一部分。这将始终包含在图像的维度内。

这个信息，以及 AImageDecoderFrameInfo 中的其他信息，对于确定帧是否独立很有用，但解码器会处理帧的混合，因此简单的顺序客户端不需要这个。

错误

• 如果 |info| 为 null，则返回空的 ARect。

此帧的新部分是否可能包含 Alpha。

在 API 31 中引入。

除非此帧是独立的（请参阅 AImageDecoder_decodeImage），否则调用一次 AImageDecoder_decodeImage 将解码更新的像素矩形，然后根据 AImageDecoderFrameInfo_getBlendOp 将其与 |pixels| 缓冲区中现有像素进行混合。此方法返回在混合之前，更新的矩形是否具有 alpha。返回值是保守的；例如，如果基于颜色索引的帧具有带有 alpha 的颜色但未使用它，此方法仍将返回 true。

这个信息，以及 AImageDecoderFrameInfo 中的其他信息，对于确定帧是否独立很有用，但解码器会处理帧的混合，因此简单的顺序客户端不需要这个。

请注意，这可能与合成帧（即混合后的结果图像）是否具有 alpha 不同。例如，如果此帧未填充整个图像尺寸（请参阅 AImageDecoderFrameInfo_getFrameRect）或它与不透明帧混合，则合成帧的 alpha 可能不匹配。

错误

• 如果 |info| 为 null，则返回 false。

报告 AImageDecoder 默认如何处理 Alpha 通道。

如果图像不包含 alpha（根据其头部信息），此方法将返回 ANDROID_BITMAP_FLAGS_ALPHA_OPAQUE。如果图像可能包含 alpha，则返回 ANDROID_BITMAP_FLAGS_ALPHA_PREMUL，因为 AImageDecoder_decodeImage 默认会预乘像素。

从 API level 30 开始可用。

从 API level 31 开始，AImageDecoder 可能包含动画的多帧，但此方法仍仅报告第一帧是否具有 alpha。

报告 AImageDecoder 默认将解码为的 AndroidBitmapFormat。

AImageDecoder 会尝试选择一种对图像和系统合理的格式。请注意，这并不表示图像的编码格式。

从 API level 30 开始可用。

报告 AImageDecoder 默认将解码为的数据空间。

默认情况下，AImageDecoder_decodeImage 不会执行任何颜色转换。

从 API level 30 开始可用。

请注意，ADataSpace 仅暴露了一些值。即使对于已命名的 ColorSpaces，如果它们没有对应的 ADataSpace，此方法也可能返回 ADATASPACE_UNKNOWN。

报告编码图像的原始高度。

除非使用 AImageDecoder_setTargetSize 选择不同的尺寸或使用 AImageDecoder_setCrop 设置裁剪矩形，否则这也是输出的逻辑像素高度。

从 API level 30 开始可用。

报告编码图像的 mimeType。

从 API level 30 开始可用。

报告编码图像的原始宽度。

除非使用 AImageDecoder_setTargetSize 选择不同的尺寸或使用 AImageDecoder_setCrop 设置裁剪矩形，否则这也是输出的逻辑像素宽度。

从 API level 30 开始可用。

前进到动画中的下一帧。

在 API 31 中引入。

AImageDecoder 在内部跟踪它准备解码的帧（“当前帧”）。最初，它被设置为解码第一帧，并且每次调用 AImageDecoder_decodeImage 都将继续解码同一帧，直到调用此方法（或 AImageDecoder_rewind）。

请注意，这可用于跳过一帧而不解码它。但有些帧依赖于（即与）先前的帧混合，而 AImageDecoder_decodeImage 假定先前的帧位于 |pixels| 缓冲区中。此外，AImageDecoder_decodeImage 处理帧的缓存和恢复（请参阅 ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS），因此跳过包含此类帧的图像中的帧可能无法产生正确的结果。

仅支持 ANDROID_BITMAP_FORMAT_RGBA_8888 和 ANDROID_BITMAP_FORMAT_RGBA_F16。

错误

• ANDROID_IMAGE_DECODER_BAD_PARAMETER：AImageDecoder 表示非动画图像（请参阅 AImageDecoder_isAnimated）或 AImageDecoder 为 null。
• 请求的 AndroidBitmapFormat 不支持动画。
• ANDROID_IMAGE_DECODER_INCOMPLETE：输入似乎已被截断。客户端必须先调用 AImageDecoder_rewind，然后才能再次调用 AImageDecoder_decodeImage。
• ANDROID_IMAGE_DECODER_ERROR：输入包含错误。客户端必须先调用 AImageDecoder_rewind，然后才能再次调用 AImageDecoder_decodeImage。
• ANDROID_IMAGE_DECODER_FINISHED：输入中没有更多帧。客户端必须先调用 AImageDecoder_rewind，然后才能再次调用 AImageDecoder_decodeImage。

计算给定 sampleSize 的尺寸。

尽管 AImageDecoder 可以缩放到任意目标尺寸（请参阅 AImageDecoder_setTargetSize），但某些尺寸可能比其他尺寸更高效。此方法计算用于达到特定 sampleSize 的最有效目标尺寸。

从 API level 30 开始可用。

错误

• ANDROID_IMAGE_DECODER_BAD_PARAMETER：AImageDecoder、|width| 或 |height| 为 null，或 |sampleSize| < 1。

从 AAsset 创建一个新的 AImageDecoder。

从 API level 30 开始可用。

错误

• ANDROID_IMAGE_DECODER_INCOMPLETE：在读取图像头部信息之前，资产被截断。
• ANDROID_IMAGE_DECODER_BAD_PARAMETER：其中一个参数为 null。
• ANDROID_IMAGE_DECODER_INVALID_INPUT：头部信息中存在错误。
• ANDROID_IMAGE_DECODER_SEEK_ERROR：资产查找失败。
• ANDROID_IMAGE_DECODER_INTERNAL_ERROR：某些其他错误，例如内存分配失败。
• ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT：不支持该格式。

从缓冲区创建新的 AImageDecoder。

从 API level 30 开始可用。

错误

• ANDROID_IMAGE_DECODER_INCOMPLETE：在读取图像头部信息之前，编码图像被截断。
• ANDROID_IMAGE_DECODER_BAD_PARAMETER：其中一个参数无效。
• ANDROID_IMAGE_DECODER_INVALID_INPUT：头部信息中存在错误。
• ANDROID_IMAGE_DECODER_INTERNAL_ERROR：某些其他错误，例如内存分配失败。
• ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT：不支持该格式。

从文件描述符创建新的 AImageDecoder。

从 API level 30 开始可用。

错误

• ANDROID_IMAGE_DECODER_INCOMPLETE：在读取图像头部信息之前，文件被截断。
• ANDROID_IMAGE_DECODER_BAD_PARAMETER：AImageDecoder 为 null，或 |fd| 不表示有效、可查找的文件描述符。
• ANDROID_IMAGE_DECODER_INVALID_INPUT：头部信息中存在错误。
• ANDROID_IMAGE_DECODER_SEEK_ERROR：描述符查找失败。
• ANDROID_IMAGE_DECODER_INTERNAL_ERROR：某些其他错误，例如内存分配失败。
• ANDROID_IMAGE_DECODER_UNSUPPORTED_FORMAT：不支持该格式。

使用 AImageDecoder 的设置将图像解码为像素。

从 API level 30 开始可用。

从 API level 31 开始，可以使用新的 API 解码动画图像（即 GIF、WebP）的所有帧。在内部，AImageDecoder 会跟踪其“当前帧”——即调用 AImageDecoder_decodeImage 将要解码的帧。创建时，当前帧始终是第一帧，多次调用此方法将每次都解码第一帧。AImageDecoder_advanceFrame 将当前帧前进到下一帧，以便将来调用此方法时将解码该帧。有些帧可能仅更新图像的一部分。它们可能仅更新子矩形（请参阅 AImageDecoderFrameInfo_getFrameRect），或者它们可能具有 alpha（请参阅 AImageDecoderFrameInfo_hasAlphaWithinBounds）。在这些情况下，此方法假定先前的帧仍驻留在 |pixels| 缓冲区中，仅解码新部分，并将其与缓冲区混合。改变整个 |pixels| 缓冲区的帧是“独立的”，不需要先前的帧保留在缓冲区中。第一帧始终是独立的。一个复杂的客户端可以使用 AImageDecoderFrameInfo 中的信息来确定其他帧是否独立，或者它们依赖于哪些帧。

如果当前帧标记为 ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS，AImageDecoder_decodeImage 将在解码之前存储 |pixels| 缓冲区（注意：这仅发生在连续的 ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS 帧序列中的第一帧）。前进到下一帧后，AImageDecoder_decodeImage 将在解码该帧之前恢复该缓冲区。这是默认行为，但可以通过将 false 传递给 AImageDecoder_setInternallyHandleDisposePrevious 来禁用它。

忽略计时信息、显示等，希望解码动画图像所有帧的客户端可以概念性地使用如下代码：

while (true) { int result = AImageDecoder_decodeImage(decoder, pixels, stride, size); if (result != ANDROID_IMAGE_DECODER_SUCCESS) break;

// 显示或保存 |pixels| 中的图像，保持缓冲区完整以便 // AImageDecoder 正确解码下一帧。 Application_viewImage(pixels);

result = AImageDecoder_advanceFrame(decoder); if (result != ANDROID_IMAGE_DECODER_SUCCESS) break; }

错误

• ANDROID_IMAGE_DECODER_INCOMPLETE：图像被截断。已解码部分图像，未解码的行已初始化为全零。
• ANDROID_IMAGE_DECODER_ERROR：图像包含错误。已解码部分图像，未解码的行已初始化为全零。
• ANDROID_IMAGE_DECODER_BAD_PARAMETER：AImageDecoder 或 |pixels| 为 null，步幅不够大或未对齐像素，或者 |size| 不够大。
• ANDROID_IMAGE_DECODER_SEEK_ERROR：资产或文件描述符查找失败。
• ANDROID_IMAGE_DECODER_INTERNAL_ERROR：某些其他错误，例如内存分配失败。
• ANDROID_IMAGE_DECODER_FINISHED：输入中没有更多帧。未发生解码。客户端必须先调用 AImageDecoder_rewind，然后才能再次调用 AImageDecoder_decodeImage。

删除 AImageDecoder。

用有关当前帧的信息填充 |info|。

在 API 31 中引入。

最初，此方法将返回有关第一帧的信息。AImageDecoder_advanceFrame 和 AImageDecoder_rewind 可用于更改当前帧。

如果图像只有一帧，此方法将使用编码信息和合理的默认值填充 AImageDecoderFrameInfo。

如果 AImageDecoder_advanceFrame 成功，此方法也将成功。

错误

• ANDROID_IMAGE_DECODER_BAD_PARAMETER：其中一个参数为 null。
• ANDROID_IMAGE_DECODER_FINISHED：输入中没有更多帧。客户端必须调用 AImageDecoder_rewind 来将当前帧重置为有效帧 (0)。

返回用于读取头部信息的不透明句柄。

此对象归 AImageDecoder 所有，并通过 AImageDecoder_delete 销毁 AImageDecoder 时会销毁。

从 API level 30 开始可用。

返回可以在 AImageDecoder_decodeImage 中使用的最小步幅。

此步幅不提供填充，这意味着它将完全等于宽度乘以所用 AndroidBitmapFormat 的每像素字节数。

如果输出被缩放（通过 AImageDecoder_setTargetSize）和/或裁剪（通过 AImageDecoder_setCrop），此方法会考虑这些因素。

从 API level 30 开始可用。

报告动画应重复多少次。

在 API 31 中引入。

这不包括首次播放。例如，重复计数为 4 意味着每帧播放 5 次。

ANDROID_IMAGE_DECODER_INFINITE 表示永远重复。

这可能需要查找。

对于非动画格式，此方法返回 0。如果编码图像包含重复计数，它可能对于只有一帧的图像返回非零值（即 AImageDecoder_isAnimated 返回 false）。

错误

• ANDROID_IMAGE_DECODER_BAD_PARAMETER：AImageDecoder 为 null。

如果图像是动画（即有多帧），则返回 true。

有多帧。

在 API 31 中引入。

单帧 GIF 被认为不是动画。这可能需要查找第一帧之后是否存在下一帧来验证。

错误

• 如果 |decoder| 为 null，则返回 false。

返回表示错误代码的常量字符串值。

在 API 31 中引入。

传递 AImageDecoder 方法（例如 AImageDecoder_decodeImage）的返回值，以获取表示错误代码的文本字符串。

错误

• 对于超出范围的值返回 null。

返回到动画的开头。

在 API 31 中引入。

此调用后，AImageDecoder 将准备好解码动画的第一帧。可以在到达动画末尾、发生错误或动画中间时调用此方法。

错误

• ANDROID_IMAGE_DECODER_BAD_PARAMETER：AImageDecoder 表示非动画图像（请参阅 AImageDecoder_isAnimated）或 AImageDecoder 为 null。
• ANDROID_IMAGE_DECODER_SEEK_ERROR：资产或文件描述符查找失败。

选择所需的输出格式。

如果编码图像表示动画，则必须在第一帧时调用此方法（例如，在调用 AImageDecoder_advanceFrame 之前或调用 AImageDecoder_rewind 之后）。

从 API level 30 开始可用。

错误

• ANDROID_IMAGE_DECODER_BAD_PARAMETER：AImageDecoder 为 null，或 |format| 不对应于 AndroidBitmapFormat。
• ANDROID_IMAGE_DECODER_INVALID_CONVERSION：AndroidBitmapFormat 与图像不兼容。
• ANDROID_IMAGE_DECODER_INVALID_STATE：动画不在第一帧。

指定缩放后（如果有）如何裁剪输出。

将来调用 AImageDecoder_decodeImage 将根据指定的 ARect 裁剪其输出。客户端只需为裁剪后的 ARect 分配足够的内存即可。

如果编码图像表示动画，则必须在第一帧时调用此方法（例如，在调用 AImageDecoder_advanceFrame 之前或调用 AImageDecoder_rewind 之后）。

从 API level 30 开始可用。

错误

• ANDROID_IMAGE_DECODER_BAD_PARAMETER：AImageDecoder 为 null，或裁剪未包含在（可能已缩放的）图像维度内。
• ANDROID_IMAGE_DECODER_INVALID_STATE：动画不在第一帧。

选择输出的数据空间。

ANDROID_BITMAP_FORMAT_A_8 会忽略此参数，因为它不支持 ADataSpace。

如果编码图像表示动画，则必须在第一帧时调用此方法（例如，在调用 AImageDecoder_advanceFrame 之前或调用 AImageDecoder_rewind 之后）。

从 API level 30 开始可用。

错误

• ANDROID_IMAGE_DECODER_BAD_PARAMETER：AImageDecoder 为 null，或 |dataspace| 不对应于 ADataSpace 值。
• ANDROID_IMAGE_DECODER_INVALID_STATE：动画不在第一帧。

是否让 AImageDecoder 在解码标记为 ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS 的帧之前存储该帧。

在 API 31 中引入。

默认为 true。许多图像不会有这样的帧（WebP 不支持它，只有部分 GIF 使用它）。但如果帧 i 是 ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS，那么 i+1 可能依赖于 i-1。当此设置项为 true 时，AImageDecoder 将防御性地将帧 i-1（即 AImageDecoder_decodeImage 中 |pixels| 的内容）复制到内部缓冲区中，以便可以用于解码 i+1。

AImageDecoder 将仅存储一帧，其尺寸由 AImageDecoder_setTargetSize 指定（如果未调用该方法，则使用原始尺寸），并在不再需要时将其丢弃。

希望手动存储此类帧的客户端可以将此设置为 false，这样 AImageDecoder 就无需存储此额外帧。相反，在解码相同的 ANDROID_IMAGE_DECODER_DISPOSE_OP_PREVIOUS 帧 i 时，AImageDecoder 将直接解码到 |pixels| 中，假定客户端已存储了 i-1。当要求解码帧 i+1 时，AImageDecoder 现在将假定客户端在 |pixels| 中提供了 i-1。

指定解码图像的输出大小。

将来调用 AImageDecoder_decodeImage 将对编码图像进行采样或缩放以达到所需尺寸。如果设置了裁剪矩形（通过 AImageDecoder_setCrop），则它必须包含在 width 和 height 指定的维度内，并且输出图像将是裁剪矩形的尺寸。

如果编码图像表示动画，则必须在第一帧时调用此方法（例如，在调用 AImageDecoder_advanceFrame 之前或调用 AImageDecoder_rewind 之后）。

强烈建议仅对缩小使用 setTargetSize，因为由于总体内存减少，渲染时放大通常比预先放大更高效。

从 API level 30 开始可用。

错误

• ANDROID_IMAGE_DECODER_BAD_PARAMETER：AImageDecoder 为 null。
• ANDROID_IMAGE_DECODER_INVALID_SCALE：|width| 或 |height| <= 0，尺寸过大，任何现有裁剪未包含在新的图像维度内，或缩放与之前调用 AImageDecoder_setUnpremultipliedRequired(true) 不兼容。
• ANDROID_IMAGE_DECODER_INVALID_STATE：动画不在第一帧。

指定输出的像素是否应为未预乘。

默认情况下，如果像素具有 alpha，AImageDecoder_decodeImage 会对像素进行预乘。将 true 传递给此方法以使其保持未预乘状态。这对不透明图像没有影响。

如果编码图像表示动画，则必须在第一帧时调用此方法（例如，在调用 AImageDecoder_advanceFrame 之前或调用 AImageDecoder_rewind 之后）。

从 API level 30 开始可用。

错误

• ANDROID_IMAGE_DECODER_INVALID_CONVERSION：由于通过 AImageDecoder_setTargetSize 设置的现有缩放，无法进行未预乘。
• ANDROID_IMAGE_DECODER_BAD_PARAMETER：AImageDecoder 为 null。
• ANDROID_IMAGE_DECODER_INVALID_STATE：动画不在第一帧。