[FFmpeg-devel] [PATCH] pixdesc: clarify AV_PIX_FMT_FLAG_ALPHA doxygen

[wm4]

Also make clear that PAL8 can have alpha.
---
Changed it quite a bit. I just want an "official" explanation how alpha
works in FFmpeg somewhere on the API. If there are still bits missing,
please tell.
---
 libavutil/pixdesc.h | 13 ++++++++++++-
 libavutil/pixfmt.h  |  4 ++--
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/libavutil/pixdesc.h b/libavutil/pixdesc.h
index 705377d..7470837 100644
--- a/libavutil/pixdesc.h
+++ b/libavutil/pixdesc.h
@@ -139,8 +139,19 @@ typedef struct AVPixFmtDescriptor {
  * An example of a pseudo-paletted format is AV_PIX_FMT_GRAY8
  */
 #define AV_PIX_FMT_FLAG_PSEUDOPAL    (1 << 6)
+
 /**
- * The pixel format has an alpha channel.
+ * The pixel format has an alpha channel. This is set on all formats that
+ * support alpha in some way. The exception is AV_PIX_FMT_PAL8, which can
+ * carry alpha as part of the palette. Details are explained in the
+ * AVPixelFormat enum, and are also encoded in the corresponding
+ * AVPixFmtDescriptor.
+ *
+ * The alpha is always straight, never pre-multiplied.
+ *
+ * If a codec or a filter does not support alpha, it should set all alpha to
+ * opaque, or use the equivalent pixel formats without alpha component, e.g.
+ * AV_PIX_FMT_RGB0 (or AV_PIX_FMT_RGB24 etc.) instead of AV_PIX_FMT_RGBA.
  */
 #define AV_PIX_FMT_FLAG_ALPHA        (1 << 7)
 
diff --git a/libavutil/pixfmt.h b/libavutil/pixfmt.h
index 5d443ce..0de9d18 100644
--- a/libavutil/pixfmt.h
+++ b/libavutil/pixfmt.h
@@ -44,11 +44,11 @@
  * big-endian CPUs.
  *
  * @par
- * When the pixel format is palettized RGB (AV_PIX_FMT_PAL8), the palettized
+ * When the pixel format is palettized ARGB (AV_PIX_FMT_PAL8), the palettized
  * image data is stored in AVFrame.data[0]. The palette is transported in
  * AVFrame.data[1], is 1024 bytes long (256 4-byte entries) and is
  * formatted the same as in AV_PIX_FMT_RGB32 described above (i.e., it is
- * also endian-specific). Note also that the individual RGB palette
+ * also endian-specific). Note also that the individual ARGB palette
  * components stored in AVFrame.data[1] should be in the range 0..255.
  * This is important as many custom PAL8 video codecs that were designed
  * to run on the IBM VGA graphics adapter use 6-bit palette components.
-- 
2.1.4