[Mesa-dev] [PATCH 2/4] DRI: Add DRIimage map and unmap functions

[Daniel Stone]

Hi,

On 22 April 2016 at 19:12, Eric Anholt <eric at anholt.net> wrote:
> I think this needs a longer comment to explain what the interface does:
>
> "Returns a map of the specified region of a __DRIimage for the specified
> usage.
>
> flags must always include __DRI_IMAGE_TRANSFER_READ and may include
> __DRI_IMAGE_TRANSFER_WRITE if the mapping is written[*].  If
> __DRI_IMAGE_TRANSFER_WRITE is not included, behavior when writing the
> mapping is undefined.

Hrm. Though the Gallium implementation currently forces READ, it seems
like drivers requiring transfer would benefit from READ being
optional, if it elides a copy of data which will just be overwritten
anyway. How about:
'flags may include __DRI_IMAGE_TRANSFER_READ, which will populate the
mapping with the current buffer content. If __DRI_IMAGE_TRANSFER_READ
is not included in the flags, the buffer content at map time is
undefined. Users wanting to modify the mapping must include
__DRI_IMAGE_TRANSFER_WRITE; if __DRI_IMAGE_TRANSFER_WRITE is not
included, behaviour when writing the mapping is undefined.'

Also, you're missing the footnote ... ?

Cheers,
Daniel