Module: Mesa Branch: gallium-resources Commit: 1dde609ad6c9d2dfa0a5f7167f3c5bcf023b7c4d URL: http://cgit.freedesktop.org/mesa/mesa/commit/?id=1dde609ad6c9d2dfa0a5f7167f3c5bcf023b7c4d
Author: Roland Scheidegger <[email protected]> Date: Wed Mar 24 02:35:00 2010 +0100 docs: some updates for pipe_resource --- src/gallium/docs/source/context.rst | 51 ++++++++++++++++++++++++++-- src/gallium/docs/source/screen.rst | 63 +++------------------------------- 2 files changed, 54 insertions(+), 60 deletions(-) diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index 2b09410..26b003a 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -239,9 +239,7 @@ Flushing Resource Busy Queries ^^^^^^^^^^^^^^^^^^^^^ -``is_texture_referenced`` - -``is_buffer_referenced`` +``is_resource_referenced`` @@ -265,3 +263,50 @@ The interfaces to these calls are likely to change to make it easier for a driver to batch multiple blits with the same source and destination. + +Transfers +^^^^^^^^^ + +These methods are used to get data to/from a resource. + +``get_transfer`` creates a transfer object. + +``transfer_destroy`` destroys the transfer object. May cause +data to be written to the resource at this point. + +``transfer_map`` creates a memory mapping for the transfer object. +The returned map is always relative to the beginning of the resource, not +taking the potential box region into account. + +.. _transfer_flush_region: +``transfer_flush_region`` If a transfer was created with TRANFER_FLUSH_EXPLICIT, +only the region specified is guaranteed to be written to. + +``transfer_unmap`` remove the memory mapping for the transfer object. +Any pointers into the map should be considered invalid and discarded. + +``transfer_inline_write`` performs a simplified transfer for simple writes. +Basically get_transfer, transfer_map, data write, transfer_unmap, and +transfer_destroy all in one. + +.. _pipe_transfer: + +PIPE_TRANSFER +^^^^^^^^^^^^^ + +These flags control the behavior of a transfer object. + +* ``READ``: resource contents are read at transfer create time. +* ``WRITE``: resource contents will be written back at transfer destroy time. +* ``MAP_DIRECTLY``: a transfer should directly map the resource. May return + NULL if not supported. +* ``DISCARD``: The memory within the mapped region is discarded. + Cannot be used with ``READ``. +* ``DONTBLOCK``: Fail if the resource cannot be mapped immediately. +* ``UNSYNCHRONIZED``: Do not synchronize pending operations on the resource + when mapping. The interaction of any writes to the map and any + operations pending on the resource are undefined. Cannot be used with + ``READ``. +* ``FLUSH_EXPLICIT``: Written ranges will be notified later with + :ref:`transfer_flush_region`. Cannot be used with + ``READ``. diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst index e78634e..294c584 100644 --- a/src/gallium/docs/source/screen.rst +++ b/src/gallium/docs/source/screen.rst @@ -126,17 +126,7 @@ handled. * ``GPU_READ``, ``GPU_WRITE``: Whether the driver will internally need to read from or write to the buffer. The latter will only happen if the buffer is made into a render target. -* ``DISCARD``: When set on a map, the contents of the map will be discarded - beforehand. Cannot be used with ``CPU_READ``. -* ``DONTBLOCK``: When set on a map, the map will fail if the buffer cannot be - mapped immediately. -* ``UNSYNCHRONIZED``: When set on a map, any outstanding operations on the - buffer will be ignored. The interaction of any writes to the map and any - operations pending with the buffer are undefined. Cannot be used with - ``CPU_READ``. -* ``FLUSH_EXPLICIT``: When set on a map, written ranges of the map require - explicit flushes using :ref:`buffer_flush_mapped_range`. Requires - ``CPU_WRITE``. + .. _pipe_texture_usage: @@ -226,56 +216,15 @@ Returns TRUE if all usages can be satisfied. ``PIPE_TEXTURE_USAGE_DYNAMIC`` is not a valid usage. -.. _texture_create: +.. _resource_create: -texture_create +resource_create ^^^^^^^^^^^^^^ -Given a template of texture setup, create a buffer and texture. +Given a template of texture setup, create a resource. -texture_blanket +resource_destroy ^^^^^^^^^^^^^^^ -Like :ref:`texture_create`, but use a supplied buffer instead of creating a -new one. - -texture_destroy -^^^^^^^^^^^^^^^ - -Destroy a texture. The buffer backing the texture is destroyed if it has no -more references. - -buffer_map -^^^^^^^^^^ - -Map a buffer into memory. - -**usage** is a bitmask of :ref:`PIPE_BUFFER_USAGE` flags. - -Returns a pointer to the map, or NULL if the mapping failed. - -buffer_map_range -^^^^^^^^^^^^^^^^ - -Map a range of a buffer into memory. - -The returned map is always relative to the beginning of the buffer, not the -beginning of the mapped range. - -.. _buffer_flush_mapped_range: - -buffer_flush_mapped_range -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Flush a range of mapped memory into a buffer. - -The buffer must have been mapped with ``PIPE_BUFFER_USAGE_FLUSH_EXPLICIT``. - -**usage** is a bitmask of :ref:`PIPE_BUFFER_USAGE` flags. - -buffer_unmap -^^^^^^^^^^^^ - -Unmap a buffer from memory. +Destroy a resource. A resource is destroyed if it has no more references. -Any pointers into the map should be considered invalid and discarded. _______________________________________________ mesa-commit mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/mesa-commit
