* ``set_vertex_buffers``
-* ``set_index_buffer``
-
Non-CSO State
^^^^^^^^^^^^^
* ``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``
blits. (Blits have their own way to pass the requisite rectangles
in.)
* ``set_tess_state`` configures the default tessellation parameters:
+
* ``default_outer_level`` is the default value for the outer tessellation
levels. This corresponds to GL's ``PATCH_DEFAULT_OUTER_LEVEL``.
* ``default_inner_level`` is the default value for the inner tessellation
levels. This corresponds to GL's ``PATCH_DEFAULT_INNER_LEVEL``.
+
* ``set_debug_callback`` sets the callback to be used for reporting
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 simple single-use uploads, use ``pipe_context::stream_uploader`` or
+``pipe_context::const_uploader``. The latter should be used for uploading
+constants, while the former should be used for uploading everything else.
+PIPE_USAGE_STREAM is implied in both cases, so don't use the uploaders
+for static allocations.
+
+Usage:
+
+Call u_upload_alloc or u_upload_data as many times as you want. After you are
+done, call u_upload_unmap. If the driver doesn't support persistent mappings,
+u_upload_unmap makes sure the previously mapped memory is unmapped.
+
+Gotchas:
+- Always fill the memory immediately after u_upload_alloc. Any following call
+to u_upload_alloc and u_upload_data can unmap memory returned by previous
+u_upload_alloc.
+- Don't interleave calls using stream_uploader and const_uploader. If you use
+one of them, do the upload, unmap, and only then can you use the other one.
+
Drawing
^^^^^^^
Every instance with instanceID in the range between ``start_instance`` and
``start_instance``+``instance_count``-1, inclusive, will be drawn.
-If there is an index buffer bound, and ``indexed`` field is true, all vertex
-indices will be looked up in the index buffer.
+If ``index_size`` != 0, all vertex indices will be looked up from the index
+buffer.
In indexed draw, ``min_index`` and ``max_index`` respectively provide a lower
and upper bound of the indices contained in the index buffer inside the range
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
^^^^^^^^^^^^^^^^^^^^^
%%%%%%%%%%%%%%%
This function flushes all pending writes to the currently-set surfaces and
-invalidates all read caches of the currently-set samplers.
+invalidates all read caches of the currently-set samplers. This can be used
+for both regular textures as well as for framebuffers read via FBFETCH.
+.. _resource_commit:
+
+resource_commit
+%%%%%%%%%%%%%%%
+
+This function changes the commit state of a part of a sparse resource. Sparse
+resources are created by setting the ``PIPE_RESOURCE_FLAG_SPARSE`` flag when
+calling ``resource_create``. Initially, sparse resources only reserve a virtual
+memory region that is not backed by memory (i.e., it is uncommitted). The
+``resource_commit`` function can be called to commit or uncommit parts (or all)
+of a resource. The driver manages the underlying backing memory.
+
+The contents of newly committed memory regions are undefined. Calling this
+function to commit an already committed memory region is allowed and leaves its
+content unchanged. Similarly, calling this function to uncommit an already
+uncommitted memory region is allowed.
+
+For buffers, the given box must be aligned to multiples of
+``PIPE_CAP_SPARSE_BUFFER_PAGE_SIZE``. As an exception to this rule, if the size
+of the buffer is not a multiple of the page size, changing the commit state of
+the last (partial) page requires a box that ends at the end of the buffer
+(i.e., box->x + box->width == buffer->width0).
+
+
+
.. _pipe_transfer:
PIPE_TRANSFER
* ``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
----------------------
projects / mesa.git / blobdiff