Commit 1dde609a authored by Roland Scheidegger's avatar Roland Scheidegger

docs: some updates for pipe_resource

parent f236f966
......@@ -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``.
......@@ -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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment