afbc.rst 7.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235
  1. .. SPDX-License-Identifier: GPL-2.0+
  2. ===================================
  3. Arm Framebuffer Compression (AFBC)
  4. ===================================
  5. AFBC is a proprietary lossless image compression protocol and format.
  6. It provides fine-grained random access and minimizes the amount of
  7. data transferred between IP blocks.
  8. AFBC can be enabled on drivers which support it via use of the AFBC
  9. format modifiers defined in drm_fourcc.h. See DRM_FORMAT_MOD_ARM_AFBC(*).
  10. All users of the AFBC modifiers must follow the usage guidelines laid
  11. out in this document, to ensure compatibility across different AFBC
  12. producers and consumers.
  13. Components and Ordering
  14. =======================
  15. AFBC streams can contain several components - where a component
  16. corresponds to a color channel (i.e. R, G, B, X, A, Y, Cb, Cr).
  17. The assignment of input/output color channels must be consistent
  18. between the encoder and the decoder for correct operation, otherwise
  19. the consumer will interpret the decoded data incorrectly.
  20. Furthermore, when the lossless colorspace transform is used
  21. (AFBC_FORMAT_MOD_YTR, which should be enabled for RGB buffers for
  22. maximum compression efficiency), the component order must be:
  23. * Component 0: R
  24. * Component 1: G
  25. * Component 2: B
  26. The component ordering is communicated via the fourcc code in the
  27. fourcc:modifier pair. In general, component '0' is considered to
  28. reside in the least-significant bits of the corresponding linear
  29. format. For example, COMP(bits):
  30. * DRM_FORMAT_ABGR8888
  31. * Component 0: R(8)
  32. * Component 1: G(8)
  33. * Component 2: B(8)
  34. * Component 3: A(8)
  35. * DRM_FORMAT_BGR888
  36. * Component 0: R(8)
  37. * Component 1: G(8)
  38. * Component 2: B(8)
  39. * DRM_FORMAT_YUYV
  40. * Component 0: Y(8)
  41. * Component 1: Cb(8, 2x1 subsampled)
  42. * Component 2: Cr(8, 2x1 subsampled)
  43. In AFBC, 'X' components are not treated any differently from any other
  44. component. Therefore, an AFBC buffer with fourcc DRM_FORMAT_XBGR8888
  45. encodes with 4 components, like so:
  46. * DRM_FORMAT_XBGR8888
  47. * Component 0: R(8)
  48. * Component 1: G(8)
  49. * Component 2: B(8)
  50. * Component 3: X(8)
  51. Please note, however, that the inclusion of a "wasted" 'X' channel is
  52. bad for compression efficiency, and so it's recommended to avoid
  53. formats containing 'X' bits. If a fourth component is
  54. required/expected by the encoder/decoder, then it is recommended to
  55. instead use an equivalent format with alpha, setting all alpha bits to
  56. '1'. If there is no requirement for a fourth component, then a format
  57. which doesn't include alpha can be used, e.g. DRM_FORMAT_BGR888.
  58. Number of Planes
  59. ================
  60. Formats which are typically multi-planar in linear layouts (e.g. YUV
  61. 420), can be encoded into one, or multiple, AFBC planes. As with
  62. component order, the encoder and decoder must agree about the number
  63. of planes in order to correctly decode the buffer. The fourcc code is
  64. used to determine the number of encoded planes in an AFBC buffer,
  65. matching the number of planes for the linear (unmodified) format.
  66. Within each plane, the component ordering also follows the fourcc
  67. code:
  68. For example:
  69. * DRM_FORMAT_YUYV: nplanes = 1
  70. * Plane 0:
  71. * Component 0: Y(8)
  72. * Component 1: Cb(8, 2x1 subsampled)
  73. * Component 2: Cr(8, 2x1 subsampled)
  74. * DRM_FORMAT_NV12: nplanes = 2
  75. * Plane 0:
  76. * Component 0: Y(8)
  77. * Plane 1:
  78. * Component 0: Cb(8, 2x1 subsampled)
  79. * Component 1: Cr(8, 2x1 subsampled)
  80. Cross-device interoperability
  81. =============================
  82. For maximum compatibility across devices, the table below defines
  83. canonical formats for use between AFBC-enabled devices. Formats which
  84. are listed here must be used exactly as specified when using the AFBC
  85. modifiers. Formats which are not listed should be avoided.
  86. .. flat-table:: AFBC formats
  87. * - Fourcc code
  88. - Description
  89. - Planes/Components
  90. * - DRM_FORMAT_ABGR2101010
  91. - 10-bit per component RGB, with 2-bit alpha
  92. - Plane 0: 4 components
  93. * Component 0: R(10)
  94. * Component 1: G(10)
  95. * Component 2: B(10)
  96. * Component 3: A(2)
  97. * - DRM_FORMAT_ABGR8888
  98. - 8-bit per component RGB, with 8-bit alpha
  99. - Plane 0: 4 components
  100. * Component 0: R(8)
  101. * Component 1: G(8)
  102. * Component 2: B(8)
  103. * Component 3: A(8)
  104. * - DRM_FORMAT_BGR888
  105. - 8-bit per component RGB
  106. - Plane 0: 3 components
  107. * Component 0: R(8)
  108. * Component 1: G(8)
  109. * Component 2: B(8)
  110. * - DRM_FORMAT_BGR565
  111. - 5/6-bit per component RGB
  112. - Plane 0: 3 components
  113. * Component 0: R(5)
  114. * Component 1: G(6)
  115. * Component 2: B(5)
  116. * - DRM_FORMAT_ABGR1555
  117. - 5-bit per component RGB, with 1-bit alpha
  118. - Plane 0: 4 components
  119. * Component 0: R(5)
  120. * Component 1: G(5)
  121. * Component 2: B(5)
  122. * Component 3: A(1)
  123. * - DRM_FORMAT_VUY888
  124. - 8-bit per component YCbCr 444, single plane
  125. - Plane 0: 3 components
  126. * Component 0: Y(8)
  127. * Component 1: Cb(8)
  128. * Component 2: Cr(8)
  129. * - DRM_FORMAT_VUY101010
  130. - 10-bit per component YCbCr 444, single plane
  131. - Plane 0: 3 components
  132. * Component 0: Y(10)
  133. * Component 1: Cb(10)
  134. * Component 2: Cr(10)
  135. * - DRM_FORMAT_YUYV
  136. - 8-bit per component YCbCr 422, single plane
  137. - Plane 0: 3 components
  138. * Component 0: Y(8)
  139. * Component 1: Cb(8, 2x1 subsampled)
  140. * Component 2: Cr(8, 2x1 subsampled)
  141. * - DRM_FORMAT_NV16
  142. - 8-bit per component YCbCr 422, two plane
  143. - Plane 0: 1 component
  144. * Component 0: Y(8)
  145. Plane 1: 2 components
  146. * Component 0: Cb(8, 2x1 subsampled)
  147. * Component 1: Cr(8, 2x1 subsampled)
  148. * - DRM_FORMAT_Y210
  149. - 10-bit per component YCbCr 422, single plane
  150. - Plane 0: 3 components
  151. * Component 0: Y(10)
  152. * Component 1: Cb(10, 2x1 subsampled)
  153. * Component 2: Cr(10, 2x1 subsampled)
  154. * - DRM_FORMAT_P210
  155. - 10-bit per component YCbCr 422, two plane
  156. - Plane 0: 1 component
  157. * Component 0: Y(10)
  158. Plane 1: 2 components
  159. * Component 0: Cb(10, 2x1 subsampled)
  160. * Component 1: Cr(10, 2x1 subsampled)
  161. * - DRM_FORMAT_YUV420_8BIT
  162. - 8-bit per component YCbCr 420, single plane
  163. - Plane 0: 3 components
  164. * Component 0: Y(8)
  165. * Component 1: Cb(8, 2x2 subsampled)
  166. * Component 2: Cr(8, 2x2 subsampled)
  167. * - DRM_FORMAT_YUV420_10BIT
  168. - 10-bit per component YCbCr 420, single plane
  169. - Plane 0: 3 components
  170. * Component 0: Y(10)
  171. * Component 1: Cb(10, 2x2 subsampled)
  172. * Component 2: Cr(10, 2x2 subsampled)
  173. * - DRM_FORMAT_NV12
  174. - 8-bit per component YCbCr 420, two plane
  175. - Plane 0: 1 component
  176. * Component 0: Y(8)
  177. Plane 1: 2 components
  178. * Component 0: Cb(8, 2x2 subsampled)
  179. * Component 1: Cr(8, 2x2 subsampled)
  180. * - DRM_FORMAT_P010
  181. - 10-bit per component YCbCr 420, two plane
  182. - Plane 0: 1 component
  183. * Component 0: Y(10)
  184. Plane 1: 2 components
  185. * Component 0: Cb(10, 2x2 subsampled)
  186. * Component 1: Cr(10, 2x2 subsampled)