at_encoder_t(3) AppleTextureEncoder at_encoder_t(3)
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_texel_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_texel_format_astc_4x4_ldr
at_texel_format_astc_8x8_ldr
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.
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
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, 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 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.
at_size_t at_encoder_get_block_dimensions (const at_encoder_t __nonnull encoder)
at_encoder_get_block_dimensions Get the size of block in the encoded image
Parameters:
encoder The at_encoder_t
Returns:
The size {x,y,z} in texels of each block in the encoded image.
at_block_format_t at_encoder_get_block_format (const at_encoder_t __nonnull encoder)
at_encoder_get_block_format Get the image type of the encoded blocks
Parameters:
encoder The at_encoder_t
Returns:
The image type of the output image. See also: at_block_format_to_MTLPixelFormat
size_t at_encoder_get_block_size (const at_encoder_t __nonnull encoder)
at_encoder_get_block_size Get the size of block in the encoded image in bytes
Parameters:
encoder The at_encoder_t
Returns:
The size in bytes of each block in the encoded image.
Author
Generated automatically by Doxygen for AppleTextureEncoder from the source code.
Version AppleTextureEncoder-1.12.12 Thu Jul 14 2016 at_encoder_t(3)