1 files changed, 41 insertions, 94 deletions
diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst
index e78634e59e..b6efd1d40c 100644
--- a/src/gallium/docs/source/screen.rst
+++ b/src/gallium/docs/source/screen.rst
@@ -103,59 +103,47 @@ For backwards compatibility, one-dimensional access to CONST register
 file is still supported. In that case, the constbuf index is assumed
 to be 0.
 
-.. _pipe_buffer_usage:
+.. _pipe_bind:
 
-PIPE_BUFFER_USAGE
-^^^^^^^^^^^^^^^^^
+PIPE_BIND
+^^^^^^^^^
 
-These flags control buffer creation. Buffers may only have one role, so
-care should be taken to not allocate a buffer with the wrong usage.
-
-* ``PIXEL``: This is the flag to use for all textures.
-* ``VERTEX``: A vertex buffer.
-* ``INDEX``: An element buffer.
-* ``CONSTANT``: A buffer of shader constants.
-
-Buffers are inevitably abstracting the pipe's underlying memory management,
-so many of their usage flags can be used to direct the way the buffer is
-handled.
-
-* ``CPU_READ``, ``CPU_WRITE``: Whether the user will map and, in the case of
-  the latter, write to, the buffer. The convenience flag ``CPU_READ_WRITE`` is
-  available to signify a read/write buffer.
-* ``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:
-
-PIPE_TEXTURE_USAGE
-^^^^^^^^^^^^^^^^^^
-
-These flags determine the possible roles a texture may be used for during its
-lifetime. Texture usage flags are cumulative and may be combined to create a
-texture that can be used as multiple things.
+These flags control resource creation. Resources may be used in different roles
+during their lifecycle. Bind flags are cumulative and may be combined to create
+a resource which can be used as multiple things.
+Depending on the pipe driver's memory management, depending on these bind flags
+resources might be created and handled quite differently.
 
 * ``RENDER_TARGET``: A color buffer or pixel buffer which will be rendered to.
 * ``DISPLAY_TARGET``: A sharable buffer that can be given to another process.
-* ``PRIMARY``: A front color buffer or scanout buffer.
 * ``DEPTH_STENCIL``: A depth (Z) buffer or stencil buffer.  Gallium does
   not explicitly provide for stencil-only buffers, so any stencil buffer
   validated here is implicitly also a depth buffer.
-* ``SAMPLER``: A texture that may be sampled from in a fragment or vertex
+* ``SAMPLER_VIEW``: A texture that may be sampled from in a fragment or vertex
   shader.
-* ``DYNAMIC``: A texture that will be mapped frequently.
+* ``VERTEX_BUFFER``: A vertex buffer.
+* ``INDEX_BUFFER``: An element buffer.
+* ``CONSTANT_BUFFER``: A buffer of shader constants.
+* ``BLIT_SOURCE``: A blit source, as given to surface_copy.
+* ``BLIT_DESTINATION``: A blit destination, as given to surface_copy and surface_fill.
+* ``TRANSFER_WRITE``: A transfer object which will be written to.
+* ``TRANSFER_READ``: A transfer object which will be read from.
+* ``CUSTOM``:
+* ``SCANOUT``: A front color buffer or scanout buffer.
+* ``SHARED``:
+
+.. _pipe_usage:
+
+PIPE_USAGE
+^^^^^^^^^^
+
+The PIPE_USAGE enums are hints about the expected lifecycle of a resource.
+* ``DEFAULT``: Expect many uploads to the resource, intermixed with draws.
+* ``DYNAMIC``: Expect many uploads to the resource, intermixed with draws.
+* ``STATIC``: Same as immutable (?)
+* ``IMMUTABLE``: Resource will not be changed after first upload.
+* ``STREAM``: Upload will be followed by draw, followed by upload, ...
+
 
 
 PIPE_TEXTURE_GEOM
@@ -218,64 +206,23 @@ is_format_supported
 
 See if a format can be used in a specific manner.
 
-**usage** is a bitmask of :ref:`PIPE_TEXTURE_USAGE` flags.
+**tex_usage** is a bitmask of :ref:`PIPE_BIND` flags.
 
 Returns TRUE if all usages can be satisfied.
 
-.. note::
-
-   ``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.
+The way a resource may be used is specifed by bind flags, :ref:`pipe_bind`.
+and hints are used to indicate to the driver what access pattern might be
+likely, :ref:`pipe_usage`.
 
-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.