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>