diff options
Diffstat (limited to 'src/gallium/docs/source')
| -rw-r--r-- | src/gallium/docs/source/context.rst | 52 | ||||
| -rw-r--r-- | src/gallium/docs/source/screen.rst | 135 |
2 files changed, 90 insertions, 97 deletions
diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index 2b0941010b0..7439d100973 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,51 @@ 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 points to the start of the mapped range according to +the box region, not the beginning of the resource. + +.. _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. This is relative to +the mapped range, not the beginning of the resource. + +``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 e78634e59e9..b6efd1d40cf 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. |