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.12Thu Jul 14 2016 at_encoder_t(3)
Mac OS X 10.12.3 - Generated Tue Feb 7 19:32:21 CST 2017