* ``set_stencil_ref`` sets the stencil front and back reference values
which are used as comparison values in stencil test.
* ``set_blend_color``
-* ``set_sample_mask``
+* ``set_sample_mask`` sets the per-context multisample sample mask. Note
+ that this takes effect even if multisampling is not explicitly enabled if
+ the frambuffer surface(s) are multisampled. Also, this mask is AND-ed
+ with the optional fragment shader sample mask output (when emitted).
+* ``set_sample_locations`` sets the sample locations used for rasterization.
+ ```get_sample_position``` still returns the default locations. When NULL,
+ the default locations are used.
* ``set_min_samples`` sets the minimum number of samples that must be run.
* ``set_clip_state``
* ``set_polygon_stipple``
various debug messages, eventually reported via KHR_debug and
similar mechanisms.
+Samplers
+^^^^^^^^
+
+pipe_sampler_state objects control how textures are sampled (coordinate
+wrap modes, interpolation modes, etc). Note that samplers are not used
+for texture buffer objects. That is, pipe_context::bind_sampler_views()
+will not bind a sampler if the corresponding sampler view refers to a
+PIPE_BUFFER resource.
Sampler Views
^^^^^^^^^^^^^
is being cast to another format. Casting can be done only between compatible
formats, that is formats that have matching component order and sizes.
-Swizzle fields specify they way in which fetched texel components are placed
+Swizzle fields specify the way in which fetched texel components are placed
in the result register. For example, ``swizzle_r`` specifies what is going to be
placed in first component of result register.
to a respective sampler view and releases a reference to the previous
sampler view.
+ Sampler views outside of ``[start_slot, start_slot + num_views)`` are
+ unmodified. If ``views`` is NULL, the behavior is the same as if
+ ``views[n]`` was NULL for the entire range, ie. releasing the reference
+ for all the sampler views in the specified range.
+
* ``create_sampler_view`` creates a new sampler view. ``texture`` is associated
with the sampler view which results in sampler view holding a reference
to the texture. Format specified in template must be compatible
* ``sampler_view_destroy`` destroys a sampler view and releases its reference
to associated texture.
+Hardware Atomic buffers
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Buffers containing hw atomics are required to support the feature
+on some drivers.
+
+Drivers that require this need to fill the ``set_hw_atomic_buffers`` method.
+
Shader Resources
^^^^^^^^^^^^^^^^
multi-byte element value starting at offset bytes from resource start, going
for size bytes. It is guaranteed that size % clear_value_size == 0.
+Evaluating Depth Buffers
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``evaluate_depth_buffer`` is a hint to decompress the current depth buffer
+assuming the current sample locations to avoid problems that could arise when
+using programmable sample locations.
+
+If a depth buffer is rendered with different sample location state than
+what is current at the time of reading the depth buffer, the values may differ
+because depth buffer compression can depend the sample locations.
+
Uploading
^^^^^^^^^
for all other cases.
This query can be used with ``render_condition``.
+In cases where a conservative approximation of an occlusion query is enough,
+``PIPE_QUERY_OCCLUSION_PREDICATE_CONSERVATIVE`` should be used. It behaves
+like ``PIPE_QUERY_OCCLUSION_PREDICATE``, except that it may return TRUE in
+additional, implementation-dependent cases.
+This query can be used with ``render_condition``.
+
``PIPE_QUERY_TIME_ELAPSED`` returns the amount of time, in nanoseconds,
the context takes to perform operations.
The result is an unsigned 64-bit integer.
unclear if it should be increased if stream output is not active.
``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` returns a boolean value indicating
-whether the stream output targets have overflowed as a result of the
+whether a selected stream output target has overflowed as a result of the
commands issued between ``begin_query`` and ``end_query``.
-This query can be used with ``render_condition``.
+This query can be used with ``render_condition``. The output stream is
+selected by the stream number passed to ``create_query``.
+
+``PIPE_QUERY_SO_OVERFLOW_ANY_PREDICATE`` returns a boolean value indicating
+whether any stream output target has overflowed as a result of the commands
+issued between ``begin_query`` and ``end_query``. This query can be used
+with ``render_condition``, and its result is the logical OR of multiple
+``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` queries, one for each stream output
+target.
``PIPE_QUERY_GPU_FINISHED`` returns a boolean value indicating whether
all commands issued before ``end_query`` have completed. However, this
If a shader type is not supported by the device/driver,
the corresponding values should be set to 0.
+``PIPE_QUERY_PIPELINE_STATISTICS_SINGLE`` returns a single counter from
+the ``PIPE_QUERY_PIPELINE_STATISTICS`` group. The specific counter must
+be selected when calling ``create_query`` by passing one of the
+``PIPE_STAT_QUERY`` enums as the query's ``index``.
+
Gallium does not guarantee the availability of any query types; one must
always check the capabilities of the :ref:`Screen` first.
equal to the context where the fence was created, fence_finish will flush
the context.
+PIPE_FLUSH_ASYNC: The flush is allowed to be asynchronous. Unlike
+``PIPE_FLUSH_DEFERRED``, the driver must still ensure that the returned fence
+will finish in finite time. However, subsequent operations in other contexts of
+the same screen are no longer guaranteed to happen after the flush. Drivers
+which use this flag must implement pipe_context::fence_server_sync.
+
+PIPE_FLUSH_HINT_FINISH: Hints to the driver that the caller will immediately
+wait for the returned fence.
+
+Additional flags may be set together with ``PIPE_FLUSH_DEFERRED`` for even
+finer-grained fences. Note that as a general rule, GPU caches may not have been
+flushed yet when these fences are signaled. Drivers are free to ignore these
+flags and create normal fences instead. At most one of the following flags can
+be specified:
+
+PIPE_FLUSH_TOP_OF_PIPE: The fence should be signaled as soon as the next
+command is ready to start executing at the top of the pipeline, before any of
+its data is actually read (including indirect draw parameters).
+
+PIPE_FLUSH_BOTTOM_OF_PIPE: The fence should be signaled as soon as the previous
+command has finished executing on the GPU entirely (but data written by the
+command may still be in caches and inaccessible to the CPU).
+
``flush_resource``
(i.e. you shouldn't use it to flush caches explicitly if you want to e.g.
use the resource for texturing)
+Fences
+^^^^^^
+
+``pipe_fence_handle``, and related methods, are used to synchronize
+execution between multiple parties. Examples include CPU <-> GPU synchronization,
+renderer <-> windowing system, multiple external APIs, etc.
+
+A ``pipe_fence_handle`` can either be 'one time use' or 're-usable'. A 'one time use'
+fence behaves like a traditional GPU fence. Once it reaches the signaled state it
+is forever considered to be signaled.
+
+Once a re-usable ``pipe_fence_handle`` becomes signaled, it can be reset
+back into an unsignaled state. The ``pipe_fence_handle`` will be reset to
+the unsignaled state by performing a wait operation on said object, i.e.
+``fence_server_sync``. As a corollary to this behaviour, a re-usable
+``pipe_fence_handle`` can only have one waiter.
+This behaviour is useful in producer <-> consumer chains. It helps avoid
+unecessarily sharing a new ``pipe_fence_handle`` each time a new frame is
+ready. Instead, the fences are exchanged once ahead of time, and access is synchronized
+through GPU signaling instead of direct producer <-> consumer communication.
+
+``fence_server_sync`` inserts a wait command into the GPU's command stream.
+
+``fence_server_signal`` inserts a signal command into the GPU's command stream.
+
+There are no guarantees that the wait/signal commands will be flushed when
+calling ``fence_server_sync`` or ``fence_server_signal``. An explicit
+call to ``flush`` is required to make sure the commands are emitted to the GPU.
+
+The Gallium implementation may implicitly ``flush`` the command stream during a
+``fence_server_sync`` or ``fence_server_signal`` call if necessary.
Resource Busy Queries
^^^^^^^^^^^^^^^^^^^^^
* ``set_device_reset_callback`` sets a callback which will be called when
a device reset is detected. The callback is only called synchronously.
+Bindless
+^^^^^^^^
+
+If PIPE_CAP_BINDLESS_TEXTURE is TRUE, the following ``pipe_context`` functions
+are used to create/delete bindless handles, and to make them resident in the
+current context when they are going to be used by shaders.
+
+* ``create_texture_handle`` creates a 64-bit unsigned integer texture handle
+ that is going to be directly used in shaders.
+* ``delete_texture_handle`` deletes a 64-bit unsigned integer texture handle.
+* ``make_texture_handle_resident`` makes a 64-bit unsigned texture handle
+ resident in the current context to be accessible by shaders for texture
+ mapping.
+* ``create_image_handle`` creates a 64-bit unsigned integer image handle that
+ is going to be directly used in shaders.
+* ``delete_image_handle`` deletes a 64-bit unsigned integer image handle.
+* ``make_image_handle_resident`` makes a 64-bit unsigned integer image handle
+ resident in the current context to be accessible by shaders for image loads,
+ stores and atomic operations.
+
Using several contexts
----------------------