- // Adds an YCbCr output. Note that you can only have one output.
- // Currently, only chunked packed output is supported, and only 4:4:4
- // (so chroma_subsampling_x and chroma_subsampling_y must both be 1).
+ // Adds an YCbCr output. Note that you can only have at most two Y'CbCr
+ // outputs, and they must have the same <ycbcr_format> and <type>.
+ // (This limitation may be lifted in the future, to allow e.g. simultaneous
+ // 8- and 10-bit output. Currently, multiple Y'CbCr outputs are only
+ // useful in some very limited circumstances, like if one texture goes
+ // to some place you cannot easily read from later.)
+ //
+ // Only 4:4:4 output is supported due to fragment shader limitations,
+ // so chroma_subsampling_x and chroma_subsampling_y must both be 1.
+ // <type> should match the data type of the FBO you are rendering to,
+ // so that if you use 16-bit output (GL_UNSIGNED_SHORT), you will get
+ // 8-, 10- or 12-bit output correctly as determined by <ycbcr_format.num_levels>.
+ // Using e.g. ycbcr_format.num_levels == 1024 with GL_UNSIGNED_BYTE is
+ // nonsensical and invokes undefined behavior.