This is an automated email from the git hooks/post-receive script. Git pushed a commit to branch master in repository ffmpeg.
commit 03ba28533baca1d9cd546202b0cb067941352474 Author: Jun Zhao <[email protected]> AuthorDate: Sat Sep 12 11:36:42 2026 +0800 Commit: Jun Zhao <[email protected]> CommitDate: Mon Sep 14 12:44:07 2026 +0000 doc: add libastcenc encoder and decoder documentation Document the Arm ASTC Encoder dependency, its required version and the installation layout configure expects, and list the new codec in the supported image formats. Describe the encoder options, supported pixel formats and profiles; make clear that floating-point input selects the HDR RGB/LDR alpha profile unless an HDR profile was requested explicitly. Describe how the decoder resolves the profile: a KTX sRGB texture is LDR, a linear KTX texture is sampled with HDR precision, and a raw ASTC stream, which publishes no profile, falls back to ldr-srgb and needs -dec_profile for HDR. Signed-off-by: Jun Zhao <[email protected]> --- doc/decoders.texi | 35 +++++++++++++++++++ doc/encoders.texi | 87 +++++++++++++++++++++++++++++++++++++++++++++++ doc/general_contents.texi | 45 ++++++++++++++++++++++++ 3 files changed, 167 insertions(+) diff --git a/doc/decoders.texi b/doc/decoders.texi index 57af9f0dbf..73348f8ee1 100644 --- a/doc/decoders.texi +++ b/doc/decoders.texi @@ -299,6 +299,41 @@ correctly by using lavc's old buggy lpc logic for decoding. @end table +@section libastcenc + +ARM ASTC Encoder wrapper for decoding ASTC textures. + +This decoder requires the Arm ASTC Encoder (astc-encoder) library version +5.4 or newer, installed as @code{astcenc/astcenc.h} next to a library that +@code{-lastcenc} finds. Pass @code{--enable-version3} together with +@code{--enable-libastcenc} to configure. + +The @file{.astc} header does not record the intended decoding profile. +Individual blocks identify their endpoint encodings, but this does not +establish the sRGB versus linear interpretation. The decoder therefore uses +the container metadata or @option{dec_profile}: a KTX sRGB texture is decoded +as @code{ldr-srgb}, while a KTX texture in the linear format is sampled with +HDR precision (@code{hdr-ldr-a}, half-float output) because the linear GL +internal format says nothing about LDR. A raw @code{.astc} file carries no +profile at all, so it falls back to @code{ldr-srgb}; use @option{dec_profile} +for a raw HDR image: + +@example +ffmpeg -dec_profile hdr-ldr-a -i input.astc output.png +@end example + +@subsection Options +@table @option +@item dec_profile @var{int} +Color profile to decode with, overriding the container metadata. It must +match the profile the texture was encoded with: @code{astcenc} substitutes +a fixed magenta error color for blocks whose endpoints do not fit the +selected profile. The values are @code{ldr}, @code{ldr-srgb}, +@code{hdr-ldr-a} and @code{hdr}. Without this option the profile published +by the container is used; a raw @file{.astc} stream, which publishes none, +falls back to @code{ldr-srgb}. +@end table + @section ffwavesynth Internal wave synthesizer. diff --git a/doc/encoders.texi b/doc/encoders.texi index 605638e040..a3ce15fcff 100644 --- a/doc/encoders.texi +++ b/doc/encoders.texi @@ -2616,6 +2616,93 @@ Text-like @end table +@section libastcenc + +ARM ASTC Encoder wrapper. + +This encoder requires the Arm ASTC Encoder (astc-encoder) library version +5.4 or newer, which provides high-quality GPU texture compression to the +ASTC format, installed as @code{astcenc/astcenc.h} next to a library that +@code{-lastcenc} finds. Pass @code{--enable-version3} together with +@code{--enable-libastcenc} to configure. + +The encoder supports both LDR (8-bit RGBA/RGB) and HDR (float/half RGBA) +input. When float or half input is detected with an LDR profile, the +profile is automatically promoted to HDR RGB with LDR alpha +(@code{HDR_RGB_LDR_A}); an explicitly selected HDR profile is kept. + +The raw bitstream can be packaged in the @file{.astc} container (16-byte +header + compressed blocks) or in the Khronos Texture 1.0 container +(@file{.ktx}). This implementation writes LDR 2D textures only through the +@file{.ktx} muxer: HDR ASTC and 3D block footprints are not supported by +the muxer and @file{.astc} must be used for them instead. The KTX 1.0 +linear ASTC GL enums do not imply LDR either, so a linear @file{.ktx} +texture may still hold HDR endpoints; such a texture is decoded with HDR +precision by default. +The @file{.ktx} muxer records its row order in a @code{KTXorientation} key. + +@subsection Pixel Format + +The encoder accepts the following pixel formats: +@itemize +@item @code{rgba} -- 8-bit packed RGBA (LDR). +@item @code{rgb24} -- 8-bit packed RGB (LDR, opaque alpha synthesized). +@item @code{rgbaf16} -- 16-bit floating-point RGBA (HDR). +@item @code{rgbaf32} -- 32-bit floating-point RGBA (HDR). +@item @code{gbrapf32} -- planar 32-bit floating-point GBR+Alpha (HDR). +@end itemize + +swscale cannot convert @emph{to} the packed floating-point formats +(@code{rgbaf16}, @code{rgbaf32}); to encode ordinary image formats as HDR, +produce a planar floating-point source instead, for example with +@code{-vf format=gbrapf32}. The packed formats are accepted when they are +supplied directly, such as from a decoder or a custom filter graph. + +@subsection Options + +@table @option + +@item block_size @var{string} +ASTC block size specified as @var{W}x@var{H}[@code{x}@var{D}]. +When the third dimension is omitted it defaults to 1 (2D block). +Valid 2D: 4x4, 5x4, 5x5, 6x5, 6x6, 8x5, 8x6, 8x8, 10x5, 10x6, +10x8, 10x10, 12x10, 12x12. Valid 3D: 3x3x3, 4x3x3, 4x4x3, 4x4x4, +5x4x4, 5x5x4, 5x5x5, 6x5x5, 6x6x5, 6x6x6. +Default is @code{8x8}. + +@item quality @var{float} +Compression quality from 0 (fastest) to 100 (slowest, exhaustive search). +Default is @code{60}. + +@item profile @var{int} +Color profile. Possible values: +@table @samp +@item ldr +Linear LDR. +@item ldr-srgb +sRGB LDR (default). +@item hdr-ldr-a +HDR RGB channels with LDR alpha channel. +@item hdr +Full HDR. +@end table + +When float/half input is detected with an LDR profile, the profile is +automatically promoted to @code{hdr-ldr-a}. Conversely, selecting an HDR +profile with 8-bit input is rejected. +This option overrides @code{AVCodecContext.profile}. When it is not set, the +profile is taken from @code{AVCodecContext.profile} (@code{AV_PROFILE_ASTC_*}), +where @code{AV_PROFILE_UNKNOWN} selects @code{ldr-srgb} as before. + +@item perceptual @var{boolean} +Use the perceptual (PSNR-weighted) error metric instead of peak-SNR. +Default is @code{0}. + +@item alpha_weight @var{boolean} +Enable per-texel alpha weighting. Default is @code{1}. + +@end table + @section libx264, libx264rgb x264 H.264/MPEG-4 AVC encoder wrapper. diff --git a/doc/general_contents.texi b/doc/general_contents.texi index ad73894d99..f1696d6ea3 100644 --- a/doc/general_contents.texi +++ b/doc/general_contents.texi @@ -13,6 +13,49 @@ Go to @url{http://aomedia.org/} and follow the instructions for installing the library. Then pass @code{--enable-libaom} to configure to enable it. +@section ARM ASTC Encoder + +FFmpeg can make use of the Arm ASTC Encoder library for ASTC image +compression and decompression in the @code{libastcenc} encoder and +decoder. + +Go to @url{https://github.com/ARM-software/astc-encoder} to obtain the +sources. Version 5.4 or newer is required, because the wrappers use the +four-argument @code{astcenc_context_alloc()} interface introduced in +that release. + +The upstream build does not install the public header, and the library file +name depends on the configured SIMD and linkage variants, so install the +pieces manually in a layout that configure can detect: the header as +@code{astcenc/astcenc.h} and a library that can be linked with +@code{-lastcenc}. Keep the library's own file name, which is the SONAME +recorded in the binary, and provide the plain name as an alias: + +@example +cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DASTCENC_SHAREDLIB=ON +cmake --build build +install -Dm644 Source/astcenc.h /usr/local/include/astcenc/astcenc.h +install -Dm755 build/Source/libastcenc-native-shared.so \ + /usr/local/lib/libastcenc-native-shared.so +ln -sf libastcenc-native-shared.so /usr/local/lib/libastcenc.so +@end example + +Use the platform's shared library suffix, and adjust the built library name +for other variants (for example @file{libastcenc-neon-shared.so} or a static +@file{libastcenc.a}), or pass @code{--extra-cflags} and +@code{--extra-ldflags} to configure if the files are installed elsewhere. +Installing only under the plain name breaks linking at run time, and the +installation directory has to be in the runtime loader's search path. + +On big-endian systems, also pass @code{-DASTCENC_ISA_NONE=ON} and +@code{-DASTCENC_BIG_ENDIAN=ON} to CMake. For this variant, install +@file{libastcenc-none-shared.so} under its own name and provide +@file{libastcenc.so} as an alias, as in the example above. + +The library is licensed under Apache-2.0, which requires version 3 of +the (L)GPL, so pass @code{--enable-version3} and +@code{--enable-libastcenc} to configure to enable it. + @section AMD AMF/VCE FFmpeg can use the AMD Advanced Media Framework library @@ -841,6 +884,8 @@ following image formats are supported: @item animated GIF @tab X @tab X @item APNG @tab X @tab X @tab Animated Portable Network Graphics +@item ASTC @tab E @tab E + @tab Adaptive Scalable Texture Compression, through external library libastcenc @item BMP @tab X @tab X @tab Microsoft BMP image @item BRender PIX @tab @tab X -- To stop receiving notification emails like this one, please contact [email protected]. _______________________________________________ ffmpeg-cvslog mailing list -- [email protected] To unsubscribe send an email to [email protected]
