gallium: document convention for get_handle calls on multi-planar resources
This adds some doc, which seems to still be a bit controversial, so opening this MR to discuss things.
In gallium drivers we have two kinds of planar resources: real planar color buffers like I420/NV12 buffers and resources with a AUX/status plane whatever you want to call it. While planar color buffers are handled via multiple pipe_resource instances chained through a next pointer (mostly because the frontend might need to handle each plane separately for lowering), the aux planes are not always exposed as a separate resources.
When the aux plane is not exposed as a chained resource the frontend can only call resource_get_handle with the base resource of the color plane and must rely on the driver to do any necessary walking internally to provide the frontend with the correct handle for the plane number specified in the winsys_handle. This is the current behaviour of the dri frontend when called on planar resources and this MR documents this convention.
The other option would be to handle the plane walking in the frontend (basically what 13859c76 did), but this requires all planes, including aux planes, to be exposed to the frontend as chained resources. As we don't know if at some point someone asks for a resource handle, we would need to always expose the chained resource for resources with more than one plane, so this might lead to some slight memory overhead.
Split from !7391 (merged)