NAME

at_encoder_t -

SYNOPSIS

#include <AppleTextureEncoder.h>

Public Member Functions

at_encoder_t __nullable OS_OBJECT_RETURNS_RETAINED at_encoder_create (at_texel_format_t texelType, at_alpha_t texelAlphaType, at_block_format_t blockType, at_alpha_t blockAlphaType, const float *__nullable backgroundColor) AT_AVAILABILITY_v1
float at_encoder_compress_texels (const at_encoder_t __nonnull encoder, const at_texel_region_t *__nonnull src, const at_block_buffer_t *__nonnull dest, float errorThreshold, at_flags_t flags) AT_AVAILABILITY_v1
at_error_t at_encoder_decompress_texels (const at_encoder_t __nonnull encoder, const at_block_buffer_t *__nonnull src, const at_texel_region_t *__nonnull dest, at_flags_t flags) AT_AVAILABILITY_v1
at_size_t at_encoder_get_block_counts (at_encoder_t __nonnull encoder, at_size_t imageSize) AT_AVAILABILITY_v1
at_size_t at_encoder_get_block_dimensions (const at_encoder_t __nonnull encoder) AT_AVAILABILITY_v1
size_t at_encoder_get_block_size (const at_encoder_t __nonnull encoder) AT_AVAILABILITY_v1
at_block_format_t at_encoder_get_block_format (const at_encoder_t __nonnull encoder) AT_AVAILABILITY_v1
at_alpha_t at_encoder_get_block_alpha (const at_encoder_t __nonnull encoder) AT_AVAILABILITY_v1
void *__nullable at_encoder_get_block_address (const at_encoder_t __nonnull encoder, at_size_t texelPosition, at_size_t imageSize, const at_block_buffer_t *__nonnull blockInfo) AT_AVAILABILITY_v1

Detailed Description

An encoder for compressing and decompressing textures into formats such as ASTC. The at_encoder_t defines an interface for an opaque object that can both compress and decompress common texture formats, such as ASTC. These formats generally comsume texels (pixels) in a small rectangular region and produce a single block of compressed data. For example, for the at_block_format_astc_4x4_ldr (MTLPixelFormatASTC_4x4_LDR) compressed texture type, the image is segmented in 4x4 rectangles. Each of these is encoded by a variety of means to a 128-bit block. When compressing an image texels are consumed and blocks are produced. When decompressing an image blocks are consumed and texels are produced. Not all encoder types are capable of both encoding and decoding.

When working with such formats, it is important to know the block size, since you generally need to stride through the image in multiples of the block size to avoid encoding artifacts at the block seams. For texel coordinates, this is given by at_encoder_get_block_dimensions(). For block coordinates, this is given by at_encoder_get_block_size().

In some cases, the at_encoder_t can work with subregions of an image. In these cases, it is said to be not monolithic. In other cases, the entire image is needed to get the right answer. Such at_encoder_ts will be tagged as monolithic. Please check at_encoder_is_compression_monolithic or at_encoder_is_decompression_monolithic as appropriate before attempting to encode or decode subregions of an image.

The at_encoder_t is an os_object. It should be released with os_release when you are done using it.

Member Function Documentation

float at_encoder_compress_texels (const at_encoder_t __nonnull encoder, const at_texel_region_t __nonnull src, const at_block_buffer_t __nonnull dest, float errorThreshold, at_flags_t flags)

at_encoder_compress_texels Encode raw texel data to a rectangular region of a block based compressed texture Some compressed texture formats such as ASTC are encoded as a grid of fixed-sized block, each encoding for a region of {MxNxO} texels. The number of texels in the block is given by the output at_texel_format used when creating the at_encoder_t.

The blocks are ordered with the x dimension increasing most rapidly, then y dimension, then z dimension. There is no padding between rows of blocks in any dimension. The position of the texel in the region of interest of the input image corresponding to the top,left corner of each block is given by:

texel_position.x = block_position.x * block_size_in_texels.x
texel_position.y = block_position.y * block_size_in_texels.y
texel_position.z = block_position.z * block_size_in_texels.z

Each block is encoded using one of a large variety of encoding methods. Some methods are more likely to work than others. These are tried first. If the accuracy of the encoding is not good enough, as determined by comparing its mean square error per normalized texel against the errorThreshold, then additional methods are tried. Some blocks may not meet the errorThreshold by any encoding method, in which case the encoding method that produced the best results is used.

If the src->validSize is not a multiple of the block size, some texels are undefined. For such texels, the nearest texel is used instead. All blocks must contain at least one valid texel or else behavior is undefined.

This function may be called from multiple threads on the same encoder concurrently.

Currently supported input formats are:

all

Currently supported output formats are:

at_block_format_astc_4x4_ldr
at_block_format_astc_8x8_ldr
at_block_format_bc1
at_block_format_bc4
at_block_format_bc5
at_block_format_bc7

Per the LDR subset of the ASTC specification, only 2D textures are supported. sRGB textures (e.g. MTLPixelFormatASTC_4x4_sRGB) should be encoded using the LDR formats, and decoded with the at_flags_srgb_linear_texels flag. There is currently no support for reading linear gamma textures with at_flags_srgb_linear_texels during encode.

Parameters:

encoder A valid at_encoder_t
src Pointer to a valid at_texel_region_t describing which texels to encode
dest Pointer to a valid at_block_buffer_t describing which ASTC blocks to overwrite
errorThreshold Mean square error per normalized texel (range [0,1]) below which to skip additional encoding attempts. Since it is square error, the minimum sensible value is 0. A value of 0 will cause the encoder to attempt all the available encodings it knows about unless one succeeds in encoding the block without loss of precision.

Common error thresholds are in the 2**-10 (fast) to 2**-15 (best quality) range.

Parameters:

flags Options to control operation of the encode filter.

Returns:

If >= 0, Success. The mean square error per normalized texel (range [0,1]) in the encode region is returned. Peak signal to noise ratio can be calculated from this number as PSNR = -10 * log10(result).

If < 0, then an error occurred and no encoding was done. All error codes are negative and have integer value. Please see at_error_t for a description of negative error codes.

at_encoder_t __nullable OS_OBJECT_RETURNS_RETAINED at_encoder_create (at_texel_format_t texelType, at_alpha_t texelAlphaType, at_block_format_t blockType, at_alpha_t blockAlphaType, const float *__nullable backgroundColor)

Create an at_encoder_t An at_encoder_t can produce convert between compressed texture blocks and raw texel data. An at_encoder_t is thread safe. A single at_encoder_t may be used from multiple threads concurrently. Use os_retain / os_release to manage the lifetime of the encoder. The at_encoder_t type supports automatic reference counting (ARC). While most operation is through its C interface, it also implements some common NSObject methods:

-debugDescription       (lldb po)
-isEqual:
-copy
-hash

The encoder can do basic transformations to image alpha as part of the operation. In some cases, this can help prevent another pass on the data. In other cases, knowledge of the alpha in the image, particularly if it is at_alpha_opaque, can help improve compression speed and image fidelity.

Parameters:

texelType The encoding of the uncompressed texel data, described by a at_texel_region_t. See description for supported types.
texelAlphaType The encoding of the alpha infomation in the uncompressed texel data
blockType The format of the compressed blocks. Indicates block size. See description for supported types.
blockAlphaType The encoding of the alpha in the compressed blocks.
backgroundColor If the input image is not opaque and the output image is opaque (outAlpha = at_alpha_opaque), then the image will be made opaque by compositing it against a opaque background color prior to encoding. If NULL, then {0} is used. Memory pointed to by backgroundColor is copied by the function and may be released immediately after the function returns. The length of the background color array is the number of color (not alpha) channels in the input image. The order of the colors matches the color space. So for BGRA data, the order is R,G,B.

Returns:

A valid at_encoder_t or NULL if an error occurred. Retain/release with os_retain / os_release

at_error_t at_encoder_decompress_texels (const at_encoder_t __nonnull encoder, const at_block_buffer_t __nonnull src, const at_texel_region_t __nonnull dest, at_flags_t flags)

at_encoder_decompress_texels Decompress a sequence of iamge blocks to texel data Some compressed texture formats such as ASTC are encoded as a grid of fixed-sized block, each encoding for a region of {MxNxO} texels. The number of texels in the block is given by the output at_texel_format used when creating the at_encoder_t.

texel_position.x = block_position.x * block_size_in_texels.x
texel_position.y = block_position.y * block_size_in_texels.y
texel_position.z = block_position.z * block_size_in_texels.z

If dest->validSize is not a multiple of the block size, Only the region covered by the dest->validSize will be overwritten.

This function may be called from multiple threads on the same encoder concurrently.

Currently supported input formats are:

all ASTC

Currently supported output formats are:

all

Per the LDR subset of the ASTC specification, only 2D textures are supported. sRGB textures (e.g. MTLPixelFormatASTC_4x4_sRGB) should be decoded using the LDR formats in conjunction with the at_flags_srgb_linear_texels flag.

Parameters:

encoder A valid at_encoder_t
src Pointer to a valid at_block_buffer_t describing which blocks to read
dest Pointer to a valid at_texel_region_t describing which texels to overwrite
flags Options to control operation of the decode filter.

Returns:

If < 0, then an error occurred and no encoding was done. All error codes are negative and have integer value. Please see at_error_t for a description of each negative error code.

void __nullable at_encoder_get_block_address (const at_encoder_t __nonnull encoder, at_size_t texelPosition, at_size_t imageSize, const at_block_buffer_t __nonnull blockInfo)

Convenience method to find the position of an encoded block based on texel position

Parameters:

encoder The at_encoder_t
texelPosition An offset into the source image, in texels. If offset is not a multiple of the block size, it will be rounded down.
imageSize The size of the image in texels
blockInfo A valid pointer to the storage where the ASTC blocks are kept

Returns:

A pointer to the block containing the texel.

at_alpha_t at_encoder_get_block_alpha (const at_encoder_t __nonnull encoder)

at_encoder_get_block_alpha Get the alpha type of the compressed blocks

Parameters:

encoder The at_encoder_t

Returns:

The alpha type of the compressed blocks

at_size_t at_encoder_get_block_counts (at_encoder_t __nonnull encoder, at_size_t imageSize)

at_encoder_get_block_counts Return the number of blocks needed to hold the encoded image size.

Parameters:

encoder The at_encoder_t
imageSize A pointer to a valid at_size_t giving the size of the input image in texels

Returns:

The size of the raw encoded ASTC image data in ATEASTCBlocks in each dimension. In a ASTC file, there is no padding between consecutive rows or slices.