There have suggestions to bake pitch alignment, address alignment, contiguous memory or other placement (hidden VRAM, GTT/BAR, etc) constraints into modifiers. Last time this was brought up it seemed like the consensus was to not allow this. Document this in drm_fourcc.h. There are several reasons for this. - Encoding all of these constraints in the modifiers would explode the search space pretty quickly (we only have 64 bits to work with). - Modifiers need to be unambiguous: a buffer can only have a single modifier. - Modifier users aren't expected to parse modifiers (except drivers). v2: add paragraph about aliases (Daniel) v3: fix unrelated changes sent with the patch v4: disambiguate users between driver and higher-level programs (Brian, Daniel) v5: fix AFBC example (Brian, Daniel) v6: remove duplicated paragraph (Daniel)
Unified · Split
| @@ -58,6 +58,30 @@ extern "C" { · 57 unmodified lines | |||
| 58 | * may preserve meaning - such as number of planes - from the fourcc code, | 58 | * may preserve meaning - such as number of planes - from the fourcc code, |
| 59 | * whereas others may not. | 59 | * whereas others may not. |
| 60 | * | 60 | * |
| 61 | * Modifiers must uniquely encode buffer layout. In other words, a buffer must | ||
| 62 | * match only a single modifier. A modifier must not be a subset of layouts of | ||
| 63 | * another modifier. For instance, it's incorrect to encode pitch alignment in | ||
| 64 | * a modifier: a buffer may match a 64-pixel aligned modifier and a 32-pixel | ||
| 65 | * aligned modifier. That said, modifiers can have implicit minimal | ||
| 66 | * requirements. | ||
| 67 | * | ||
| 68 | * For modifiers where the combination of fourcc code and modifier can alias, | ||
| 69 | * a canonical pair needs to be defined and used by all drivers. Preferred | ||
| 70 | * combinations are also encouraged where all combinations might lead to | ||
| 71 | * confusion and unnecessarily reduced interoperability. An example for the | ||
| 72 | * latter is AFBC, where the ABGR layouts are preferred over ARGB layouts. | ||
| 73 | * | ||
| 74 | * There are two kinds of modifier users: | ||
| 75 | * | ||
| 76 | * - Kernel and user-space drivers: for drivers it's important that modifiers | ||
| 77 | * don't alias, otherwise two drivers might support the same format but use | ||
| 78 | * different aliases, preventing them from sharing buffers in an efficient | ||
| 79 | * format. | ||
| 80 | * - Higher-level programs interfacing with KMS/GBM/EGL/Vulkan/etc: these users | ||
| 81 | * see modifiers as opaque tokens they can check for equality and intersect. | ||
| 82 | * These users musn't need to know to reason about the modifier value | ||
| 83 | * (i.e. they are not expected to extract information out of the modifier). | ||
| 84 | * | ||
| 61 | * Vendors should document their modifier usage in as much detail as | 85 | * Vendors should document their modifier usage in as much detail as |
| 62 | * possible, to ensure maximum compatibility across devices, drivers and | 86 | * possible, to ensure maximum compatibility across devices, drivers and |
| 63 | * applications. | 87 | * applications. |