renderonly: write down usage rules
authorSimon Ser <contact@emersion.fr>
Tue, 17 Aug 2021 16:43:45 +0000 (18:43 +0200)
committerSimon Ser <contact@emersion.fr>
Mon, 20 Dec 2021 11:42:03 +0000 (12:42 +0100)
commit0a9886cc45e5dd8ef8c041f490b79c6be4150881
treeb649b9f9a93ee996946b82e91004bac6d5e0e9f3
parentd4af7d25198ecfaac65fb58cd76da0640b042936
renderonly: write down usage rules

The renderonly helpers are extremely easy to mis-use. Write down
the expectations.

I've seen *many* mistakes in the past, including:

- Forgetting to create the scanout resource on import [1] [2], causing
  bugs such as [3].
- Assuming the scanout resource always exists [4].
- Returning a GEM handle valid for the driver's internal DRM FD, but
  invalid for the caller's DRM FD [5].
- Not implementing resource_get_param, breaking stride/offset/modifier
  queries when no scanout resource is available [6] [7].

Signed-off-by: Simon Ser <contact@emersion.fr>
Reviewed-by: Lucas Stach <l.stach@pengutronix.de>
Reviewed-by: Daniel Stone <daniels@collabora.com>
[1]: https://gitlab.freedesktop.org/mesa/mesa/-/commit/4aac98f8a68b4c6407a5f41a91bfd7763f0607d7
[2]: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/12018
[3]: https://github.com/swaywm/wlroots/issues/2795
[4]: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/12081
[5]: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/12074
[6]: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/12362
[7]: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/12370

Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/12418>
src/gallium/auxiliary/renderonly/renderonly.h