shared/pixel-formats.h

   1 /*
   2  * Copyright © 2016, 2019 Collabora, Ltd.
   3  * Copyright (c) 2018 DisplayLink (UK) Ltd.
   4  *
   5  * Permission is hereby granted, free of charge, to any person obtaining a
   6  * copy of this software and associated documentation files (the "Software"),
   7  * to deal in the Software without restriction, including without limitation
   8  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
   9  * and/or sell copies of the Software, and to permit persons to whom the
  10  * Software is furnished to do so, subject to the following conditions:
  11  *
  12  * The above copyright notice and this permission notice (including the next
  13  * paragraph) shall be included in all copies or substantial portions of the
  14  * Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  19  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  22  * DEALINGS IN THE SOFTWARE.
  23  *
  24  * Author: Daniel Stone <daniels@collabora.com>
  25  */
  26
  27 #include <inttypes.h>
  28 #include <stdbool.h>
  29 #include <pixman.h>
  30
  31 /**
  32  * Contains information about pixel formats, mapping format codes from
  33  * wl_shm and drm_fourcc.h (which are deliberately identical, but for the
  34  * special cases of WL_SHM_ARGB8888 and WL_SHM_XRGB8888) into various
  35  * sets of information. Helper functions are provided for dealing with these
  36  * raw structures.
  37  */
  38 struct pixel_format_info {
  39         /** DRM/wl_shm format code */
  40         uint32_t format;
  41
  42         /** The DRM format name without the DRM_FORMAT_ prefix. */
  43         const char *drm_format_name;
  44
  45         /** If true, is only for internal use and should not be advertised to
  46          * clients to allow them to create buffers of this format. */
  47         bool hide_from_clients;
  48
  49         /** If non-zero, number of planes in base (non-modified) format. */
  50         int num_planes;
  51
  52         /** If format contains alpha channel, opaque equivalent of format,
  53          *  i.e. alpha channel replaced with X. */
  54         uint32_t opaque_substitute;
  55
  56         /** How the format should be sampled, expressed in terms of tokens
  57          *  from the EGL_WL_bind_wayland_display extension. If not set,
  58          *  assumed to be either RGB or RGBA, depending on whether or not
  59          *  the format contains an alpha channel. The samplers may still
  60          *  return alpha even for opaque formats; users must manually set
  61          *  the alpha channel to 1.0 (or ignore it) if the format is
  62          *  opaque. */
  63         uint32_t sampler_type;
  64
  65         /** GL internal format; to be used when creating FBO renderbuffers */
  66         int gl_internalformat;
  67
  68         /** GL format, if data can be natively/directly uploaded. Note that
  69          *  whilst DRM formats are little-endian unless explicitly specified,
  70          *  (i.e. DRM_FORMAT_ARGB8888 is stored BGRA as sequential bytes in
  71          *  memory), GL uses the sequential byte order, so that format maps to
  72          *  GL_BGRA_EXT plus GL_UNSIGNED_BYTE. To add to the confusion, the
  73          *  explicitly-sized types (e.g. GL_UNSIGNED_SHORT_5_5_5_1) read in
  74          *  machine-endian order, so for these types, the correspondence
  75          *  depends on endianness. */
  76         int gl_format;
  77
  78         /** GL data type, if data can be natively/directly uploaded. */
  79         int gl_type;
  80
  81         /** Pixman data type, if it agrees exactly with the wl_shm format */
  82         pixman_format_code_t pixman_format;
  83
  84         /** If set, this format can be used with the legacy drmModeAddFB()
  85          *  function (not AddFB2), using this and the bpp member. */
  86         int addfb_legacy_depth;
  87
  88         /** Number of bits required to store a single pixel, for
  89          *  single-planar formats. */
  90         int bpp;
  91
  92         /** Horizontal subsampling; if non-zero, divide the width by this
  93          *  member to obtain the number of columns in the source buffer for
  94          *  secondary planes only. Stride is not affected by horizontal
  95          *  subsampling. */
  96         int hsub;
  97
  98         /** Vertical subsampling; if non-zero, divide the height by this
  99          *  member to obtain the number of rows in the source buffer for
 100          *  secondary planes only. */
 101         int vsub;
 102
 103         /* Ordering of chroma components. */
 104         enum {
 105                 ORDER_UV = 0,
 106                 ORDER_VU,
 107         } chroma_order;
 108
 109         /* If packed YUV (num_planes == 1), ordering of luma/chroma
 110          * components. */
 111         enum {
 112                 ORDER_LUMA_CHROMA = 0,
 113                 ORDER_CHROMA_LUMA,
 114         } luma_chroma_order;
 115
 116         /** How many significant bits each channel has, or zero if N/A. */
 117         struct {
 118                 int r;
 119                 int g;
 120                 int b;
 121                 int a;
 122         } bits;
 123
 124         /** How channel bits are interpreted, fixed (uint) or floating-point */
 125         enum {
 126                 PIXEL_COMPONENT_TYPE_FIXED = 0,
 127                 PIXEL_COMPONENT_TYPE_FLOAT,
 128         } component_type;
 129 };
 130
 131 /**
 132  * Get pixel format information for a DRM format code
 133  *
 134  * Given a DRM format code, return a pixel format info structure describing
 135  * the properties of that format.
 136  *
 137  * @param format DRM format code to get info for
 138  * @returns A pixel format structure (must not be freed), or NULL if the
 139  *          format could not be found
 140  */
 141 const struct pixel_format_info *
 142 pixel_format_get_info(uint32_t format);
 143
 144 /**
 145  * Get pixel format information for a SHM format code
 146  *
 147  * Given a SHM format code, return a DRM pixel format info structure describing
 148  * the properties of that format.
 149  *
 150  * @param format SHM format code to get info for.
 151  * @returns A pixel format structure (must not be freed), or NULL if the
 152  *          format could not be found.
 153  */
 154 const struct pixel_format_info *
 155 pixel_format_get_info_shm(uint32_t format);
 156
 157 /**
 158  * Get pixel format information by table index
 159  *
 160  * Given a 0-based index in the format table, return the corresponding
 161  * DRM pixel format info structure.
 162  *
 163  * @param index Index of the pixel format in the table
 164  * @returns A pixel format structure (must not be freed), or NULL if the
 165  *          index is out of range.
 166  */
 167 const struct pixel_format_info *
 168 pixel_format_get_info_by_index(unsigned int index);
 169
 170 /**
 171  * Return the size of the pixel format table
 172  *
 173  * @returns The number of entries in the pixel format table
 174  */
 175 unsigned int
 176 pixel_format_get_info_count(void);
 177
 178 /**
 179  * Get pixel format information for a named DRM format
 180  *
 181  * Given a DRM format name, return a pixel format info structure describing
 182  * the properties of that format.
 183  *
 184  * The DRM format name is the preprocessor token name from drm_fourcc.h
 185  * without the DRM_FORMAT_ prefix. The search is also case-insensitive.
 186  * Both "xrgb8888" and "XRGB8888" searches will find DRM_FORMAT_XRGB8888
 187  * for example.
 188  *
 189  * @param drm_format_name DRM format name to get info for (not NULL)
 190  * @returns A pixel format structure (must not be freed), or NULL if the
 191  *          name could not be found
 192  */
 193 const struct pixel_format_info *
 194 pixel_format_get_info_by_drm_name(const char *drm_format_name);
 195
 196 /**
 197  * Get pixel format information for a Pixman format code
 198  *
 199  * Given a Pixman format code, return a pixel format info structure describing
 200  * the properties of that format.
 201  *
 202  * @param pixman_format Pixman format code to get info for
 203  * @returns A pixel format structure (must not be freed), or NULL if the
 204  *          format could not be found
 205  */
 206 const struct pixel_format_info *
 207 pixel_format_get_info_by_pixman(pixman_format_code_t pixman_format);
 208
 209 /**
 210  * Get number of planes used by a pixel format
 211  *
 212  * Given a pixel format info structure, return the number of planes
 213  * required for a buffer. Note that this is not necessarily identical to
 214  * the number of samplers required to be bound, as two views into a single
 215  * plane are sometimes required.
 216  *
 217  * @param format Pixel format info structure
 218  * @returns Number of planes required for the format
 219  */
 220 unsigned int
 221 pixel_format_get_plane_count(const struct pixel_format_info *format);
 222
 223 /**
 224  * Determine if a pixel format is opaque or contains alpha
 225  *
 226  * Returns whether or not the pixel format is opaque, or contains a
 227  * significant alpha channel. Note that the suggested EGL sampler type may
 228  * still sample undefined data into the alpha channel; users must consider
 229  * alpha as 1.0 if the format is opaque, and not rely on the sampler to
 230  * return this when sampling from the alpha channel.
 231  *
 232  * @param format Pixel format info structure
 233  * @returns True if the format is opaque, or false if it has significant alpha
 234  */
 235 bool
 236 pixel_format_is_opaque(const struct pixel_format_info *format);
 237
 238 /**
 239  * Get compatible opaque equivalent for a format
 240  *
 241  * Given a pixel format info structure, return a format which is wholly
 242  * compatible with the input format, but opaque, ignoring the alpha channel.
 243  * If an alpha format is provided, but the content is known to all be opaque,
 244  * then this can be used as a substitute to avoid blending.
 245  *
 246  * If the input format is opaque, this function will return the input format.
 247  *
 248  * @param format Pixel format info structure
 249  * @returns A pixel format info structure for the compatible opaque substitute
 250  */
 251 const struct pixel_format_info *
 252 pixel_format_get_opaque_substitute(const struct pixel_format_info *format);
 253
 254 /**
 255  * For an opaque format, get the equivalent format with alpha instead of an
 256  * ignored channel
 257  *
 258  * This is the opposite lookup from pixel_format_get_opaque_substitute().
 259  * Finds the format whose opaque substitute is the given format.
 260  *
 261  * If the input format is not opaque or does not have ignored (X) bits, then
 262  * the search cannot find a match.
 263  *
 264  * @param format DRM format code to search for
 265  * @returns A pixel format info structure for the pixel format whose opaque
 266  * substitute is the argument, or NULL if no match.
 267  */
 268 const struct pixel_format_info *
 269 pixel_format_get_info_by_opaque_substitute(uint32_t format);
 270
 271 /**
 272  * Return the horizontal subsampling factor for a given plane
 273  *
 274  * When horizontal subsampling is effective, a sampler bound to a secondary
 275  * plane must bind the sampler with a smaller effective width. This function
 276  * returns the subsampling factor to use for the given plane.
 277  *
 278  * @param format Pixel format info structure
 279  * @param plane Zero-indexed plane number
 280  * @returns Horizontal subsampling factor for the given plane
 281  */
 282 unsigned int
 283 pixel_format_hsub(const struct pixel_format_info *format,
 284                   unsigned int plane);
 285
 286 /**
 287  * Return the vertical subsampling factor for a given plane
 288  *
 289  * When vertical subsampling is effective, a sampler bound to a secondary
 290  * plane must bind the sampler with a smaller effective height. This function
 291  * returns the subsampling factor to use for the given plane.
 292  *
 293  * @param format Pixel format info structure
 294  * @param plane Zero-indexed plane number
 295  * @returns Vertical subsampling factor for the given plane
 296  */
 297 unsigned int
 298 pixel_format_vsub(const struct pixel_format_info *format,
 299                   unsigned int plane);
 300
 301 /**
 302  * Return the effective sampling width for a given plane
 303  *
 304  * When horizontal subsampling is effective, a sampler bound to a secondary
 305  * plane must bind the sampler with a smaller effective width. This function
 306  * returns the effective width to use for the sampler, i.e. dividing by hsub.
 307  *
 308  * If horizontal subsampling is not in effect, this will be equal to the
 309  * width.
 310  *
 311  * @param format Pixel format info structure
 312  * @param plane Zero-indexed plane number
 313  * @param width Width of the buffer
 314  * @returns Effective width for sampling
 315  */
 316 unsigned int
 317 pixel_format_width_for_plane(const struct pixel_format_info *format,
 318                              unsigned int plane,
 319                              unsigned int width);
 320
 321 /**
 322  * Return the effective sampling height for a given plane
 323  *
 324  * When vertical subsampling is in effect, a sampler bound to a secondary
 325  * plane must bind the sampler with a smaller effective height. This function
 326  * returns the effective height to use for the sampler, i.e. dividing by vsub.
 327  *
 328  * If vertical subsampling is not in effect, this will be equal to the height.
 329  *
 330  * @param format Pixel format info structure
 331  * @param plane Zero-indexed plane number
 332  * @param height Height of the buffer
 333  * @returns Effective width for sampling
 334  */
 335 unsigned int
 336 pixel_format_height_for_plane(const struct pixel_format_info *format,
 337                               unsigned int plane,
 338                               unsigned int height);
 339 /**
 340  * Return a human-readable format modifier. Comprised from the modifier name,
 341  * the vendor name, and the original encoded value in hexadecimal, using
 342  * 'VENDOR_NAME_MODIFIER_NAME (modifier_encoded_value)' pattern. In case the
 343  * modifier name (and the vendor name) isn't found, this returns the original
 344  * encoded value, as a string value.
 345  *
 346  * @param modifier  the modifier in question
 347  * @returns a malloc'ed string, caller responsible for freeing after use.
 348  */
 349 char *
 350 pixel_format_get_modifier(uint64_t modifier);
 351
 352 /**
 353  * Return the wl_shm format code
 354  *
 355  * @param info Pixel format info structure
 356  * @returns The wl_shm format code for this pixel format.
 357  */
 358 uint32_t
 359 pixel_format_get_shm_format(const struct pixel_format_info *info);
 360
 361 /**
 362  * Get pixel format array for an array of DRM format codes
 363  *
 364  * Given an array of DRM format codes, return an array of corresponding pixel
 365  * format info pointers.
 366  *
 367  * @param formats Array of DRM format codes to get info for
 368  * @param formats_count Number of entries in formats.
 369  * @returns An array of pixel format info pointers, or NULL if any format could
 370  *          not be found. Must be freed by the caller.
 371  */
 372 const struct pixel_format_info **
 373 pixel_format_get_array(const uint32_t *formats, unsigned int formats_count);