diff options
Diffstat (limited to 'src/gallium/docs')
| -rw-r--r-- | src/gallium/docs/d3d11ddi.txt | 1 | ||||
| -rw-r--r-- | src/gallium/docs/source/context.rst | 113 | ||||
| -rw-r--r-- | src/gallium/docs/source/screen.rst | 2 | ||||
| -rw-r--r-- | src/gallium/docs/source/tgsi.rst | 170 |
4 files changed, 260 insertions, 26 deletions
diff --git a/src/gallium/docs/d3d11ddi.txt b/src/gallium/docs/d3d11ddi.txt index 11e77190895..0a9e7e50f1d 100644 --- a/src/gallium/docs/d3d11ddi.txt +++ b/src/gallium/docs/d3d11ddi.txt @@ -337,7 +337,6 @@ IaSetTopology + Gallium supports line loops, triangle fans, quads, quad strips and polygons IaSetVertexBuffers -> set_vertex_buffers - + Gallium allows to specify a max_index here - Gallium only allows setting all vertex buffers at once, while D3D11 supports setting a subset OpenResource -> texture_from_handle diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index 6760e7be4b9..c6812cd309e 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -3,8 +3,12 @@ Context ======= -The context object represents the purest, most directly accessible, abilities -of the device's 3D rendering pipeline. +A Gallium rendering context encapsulates the state which effects 3D +rendering such as blend state, depth/stencil state, texture samplers, +etc. + +Note that resource/texture allocation is not per-context but per-screen. + Methods ------- @@ -12,20 +16,23 @@ Methods CSO State ^^^^^^^^^ -All CSO state is created, bound, and destroyed, with triplets of methods that -all follow a specific naming scheme. For example, ``create_blend_state``, -``bind_blend_state``, and ``destroy_blend_state``. +All Constant State Object (CSO) state is created, bound, and destroyed, +with triplets of methods that all follow a specific naming scheme. +For example, ``create_blend_state``, ``bind_blend_state``, and +``destroy_blend_state``. CSO objects handled by the context object: * :ref:`Blend`: ``*_blend_state`` -* :ref:`Sampler`: These are special; they can be bound to either vertex or - fragment samplers, and they are bound in groups. - ``bind_fragment_sampler_states``, ``bind_vertex_sampler_states`` +* :ref:`Sampler`: Texture sampler states are bound separately for fragment, + vertex and geometry samplers. Note that sampler states are set en masse. + If M is the max number of sampler units supported by the driver and N + samplers are bound with ``bind_fragment_sampler_states`` then sampler + units N..M-1 are considered disabled/NULL. * :ref:`Rasterizer`: ``*_rasterizer_state`` * :ref:`Depth, Stencil, & Alpha`: ``*_depth_stencil_alpha_state`` -* :ref:`Shader`: These have two sets of methods. ``*_fs_state`` is for - fragment shaders, and ``*_vs_state`` is for vertex shaders. +* :ref:`Shader`: These are create, bind and destroy methods for vertex, + fragment and geometry shaders. * :ref:`Vertex Elements`: ``*_vertex_elements_state`` @@ -47,6 +54,9 @@ buffers, surfaces) are bound to the driver. * ``set_index_buffer`` +* ``set_stream_output_buffers`` + + Non-CSO State ^^^^^^^^^^^^^ @@ -96,7 +106,9 @@ to the array index which is used for sampling. * ``set_fragment_sampler_views`` binds an array of sampler views to fragment shader stage. Every binding point acquires a reference to a respective sampler view and releases a reference to the previous - sampler view. + sampler view. If M is the maximum number of sampler units and N units + is passed to set_fragment_sampler_views, the driver should unbind the + sampler views for units N..M-1. * ``set_vertex_sampler_views`` binds an array of sampler views to vertex shader stage. Every binding point acquires a reference to a respective @@ -233,6 +245,11 @@ The most common type of query is the occlusion query, are written to the framebuffer without being culled by :ref:`Depth, Stencil, & Alpha` testing or shader KILL instructions. The result is an unsigned 64-bit integer. +In cases where a boolean result of an occlusion query is enough, +``PIPE_QUERY_OCCLUSION_PREDICATE`` should be used. It is just like +``PIPE_QUERY_OCCLUSION_COUNTER`` except that the result is a boolean +value of FALSE for cases where COUNTER would result in 0 and TRUE +for all other cases. Another type of query, ``PIPE_QUERY_TIME_ELAPSED``, returns the amount of time, in nanoseconds, the context takes to perform operations. @@ -349,6 +366,22 @@ Any pointers into the map should be considered invalid and discarded. Basically get_transfer, transfer_map, data write, transfer_unmap, and transfer_destroy all in one. + +The box parameter to some of these functions defines a 1D, 2D or 3D +region of pixels. This is self-explanatory for 1D, 2D and 3D texture +targets. + +For PIPE_TEXTURE_1D_ARRAY, the box::y and box::height fields refer to the +array dimension of the texture. + +For PIPE_TEXTURE_2D_ARRAY, the box::z and box::depth fields refer to the +array dimension of the texture. + +For PIPE_TEXTURE_CUBE, the box:z and box::depth fields refer to the +faces of the cube map (z + depth <= 6). + + + .. _transfer_flush_region: transfer_flush_region @@ -359,6 +392,22 @@ be flushed on write or unmap. Flushes must be requested with ``transfer_flush_region``. Flush ranges are relative to the mapped range, not the beginning of the resource. + + +.. _redefine_user_buffer: + +redefine_user_buffer +%%%%%%%%%%%%%%%%%%%% + +This function notifies a driver that the user buffer content has been changed. +The updated region starts at ``offset`` and is ``size`` bytes large. +The ``offset`` is relative to the pointer specified in ``user_buffer_create``. +While uploading the user buffer, the driver is allowed not to upload +the memory outside of this region. +The width0 is redefined to ``MAX2(width0, offset+size)``. + + + .. _pipe_transfer: PIPE_TRANSFER @@ -366,16 +415,32 @@ 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``. +``PIPE_TRANSFER_READ`` + Resource contents read back (or accessed directly) at transfer create time. + +``PIPE_TRANSFER_WRITE`` + Resource contents will be written back at transfer_destroy time (or modified + as a result of being accessed directly). + +``PIPE_TRANSFER_MAP_DIRECTLY`` + a transfer should directly map the resource. May return NULL if not supported. + +``PIPE_TRANSFER_DISCARD_RANGE`` + The memory within the mapped region is discarded. Cannot be used with + ``PIPE_TRANSFER_READ``. + +``PIPE_TRANSFER_DISCARD_WHOLE_RESOURCE`` + Discards all memory backing the resource. It should not be used with + ``PIPE_TRANSFER_READ``. + +``PIPE_TRANSFER_DONTBLOCK`` + Fail if the resource cannot be mapped immediately. + +``PIPE_TRANSFER_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 ``PIPE_TRANSFER_READ``. + +``PIPE_TRANSFER_FLUSH_EXPLICIT`` + Written ranges will be notified later with :ref:`transfer_flush_region`. + Cannot be used with ``PIPE_TRANSFER_READ``. diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst index ab90097add6..976e75bed04 100644 --- a/src/gallium/docs/source/screen.rst +++ b/src/gallium/docs/source/screen.rst @@ -273,7 +273,7 @@ Modern APIs allow using buffers as shader resources. **depth0** the depth of the base mip level of the texture (1 for everything else). -**array_size the array size for 1D and 2D array textures. +**array_size** the array size for 1D and 2D array textures. For cube maps this must be 6, for other textures 1. **last_level** the last mip map level present. diff --git a/src/gallium/docs/source/tgsi.rst b/src/gallium/docs/source/tgsi.rst index d986e6601e6..4debcc6ecc4 100644 --- a/src/gallium/docs/source/tgsi.rst +++ b/src/gallium/docs/source/tgsi.rst @@ -1250,6 +1250,157 @@ This opcode is the inverse of :opcode:`DFRACEXP`. dst.zw = \sqrt{src.zw} +.. _resourceopcodes: + +Resource Access Opcodes +^^^^^^^^^^^^^^^^^^^^^^^^ + +Those opcodes follow very closely semantics of the respective Direct3D +instructions. If in doubt double check Direct3D documentation. + +.. opcode:: LOAD - Simplified alternative to the "SAMPLE" instruction. + Using the provided integer address, LOAD fetches data + from the specified buffer/texture without any filtering. + The source data may come from any resource type other + than CUBE. + LOAD dst, address, resource + e.g. + LOAD TEMP[0], TEMP[1], RES[0] + The 'address' is specified as unsigned integers. If the + 'address' is out of range [0...(# texels - 1)] the + result of the fetch is always 0 in all components. + As such the instruction doesn't honor address wrap + modes, in cases where that behavior is desirable + 'sample' instruction should be used. + address.w always provides an unsigned integer mipmap + level. If the value is out of the range then the + instruction always returns 0 in all components. + address.yz are ignored for buffers and 1d textures. + address.z is ignored for 1d texture arrays and 2d + textures. + For 1D texture arrays address.y provides the array + index (also as unsigned integer). If the value is + out of the range of available array indices + [0... (array size - 1)] then the opcode always returns + 0 in all components. + For 2D texture arrays address.z provides the array + index, otherwise it exhibits the same behavior as in + the case for 1D texture arrays. + The exeact semantics of the source address are presented + in the table below: + resource type X Y Z W + ------------- ------------------------ + PIPE_BUFFER x ignored + PIPE_TEXTURE_1D x mpl + PIPE_TEXTURE_2D x y mpl + PIPE_TEXTURE_3D x y z mpl + PIPE_TEXTURE_RECT x y mpl + PIPE_TEXTURE_CUBE not allowed as source + PIPE_TEXTURE_1D_ARRAY x idx mpl + PIPE_TEXTURE_2D_ARRAY x y idx mpl + + Where 'mpl' is a mipmap level and 'idx' is the + array index. + + +.. opcode:: LOAD_MS - Just like LOAD but allows fetch data from + multi-sampled surfaces. + +.. opcode:: SAMPLE - Using provided address, sample data from the + specified texture using the filtering mode identified + by the gven sampler. The source data may come from + any resource type other than buffers. + SAMPLE dst, address, resource, sampler + e.g. + SAMPLE TEMP[0], TEMP[1], RES[0], SAMP[0] + +.. opcode:: SAMPLE_B - Just like the SAMPLE instruction with the + exception that an additiona bias is applied to the + level of detail computed as part of the instruction + execution. + SAMPLE_B dst, address, resource, sampler, lod_bias + e.g. + SAMPLE_B TEMP[0], TEMP[1], RES[0], SAMP[0], TEMP[2].x + +.. opcode:: SAMPLE_C - Similar to the SAMPLE instruction but it + performs a comparison filter. The operands to SAMPLE_C + are identical to SAMPLE, except that tere is an additional + float32 operand, reference value, which must be a register + with single-component, or a scalar literal. + SAMPLE_C makes the hardware use the current samplers + compare_func (in pipe_sampler_state) to compare + reference value against the red component value for the + surce resource at each texel that the currently configured + texture filter covers based on the provided coordinates. + SAMPLE_C dst, address, resource.r, sampler, ref_value + e.g. + SAMPLE_C TEMP[0], TEMP[1], RES[0].r, SAMP[0], TEMP[2].x + +.. opcode:: SAMPLE_C_LZ - Same as SAMPLE_C, but LOD is 0 and derivatives + are ignored. The LZ stands for level-zero. + SAMPLE_C_LZ dst, address, resource.r, sampler, ref_value + e.g. + SAMPLE_C_LZ TEMP[0], TEMP[1], RES[0].r, SAMP[0], TEMP[2].x + + +.. opcode:: SAMPLE_D - SAMPLE_D is identical to the SAMPLE opcode except + that the derivatives for the source address in the x + direction and the y direction are provided by extra + parameters. + SAMPLE_D dst, address, resource, sampler, der_x, der_y + e.g. + SAMPLE_D TEMP[0], TEMP[1], RES[0], SAMP[0], TEMP[2], TEMP[3] + +.. opcode:: SAMPLE_L - SAMPLE_L is identical to the SAMPLE opcode except + that the LOD is provided directly as a scalar value, + representing no anisotropy. Source addresses A channel + is used as the LOD. + SAMPLE_L dst, address, resource, sampler + e.g. + SAMPLE_L TEMP[0], TEMP[1], RES[0], SAMP[0] + + +.. opcode:: GATHER4 - Gathers the four texels to be used in a bi-linear + filtering operation and packs them into a single register. + Only woth with 2D, 2D array, cubemaps, and cubemaps arrays. + For 2D textures, only the addressing modes of the sampler and + the top level of any mip pyramid are used. Set W to zero. + It behaves like the SAMPLE instruction, but a filtered + sample is not generated. The four samples that contribute + to filtering are places into xyzw in cunter-clockwise order, + starting with the (u,v) texture coordinate delta at the + following locations (-, +), (+, +), (+, -), (-, -), where + the magnitude of the deltas are half a texel. + + +.. opcode:: RESINFO - query the dimensions of a given input buffer. + dst receives width, height, depth or array size and + number of mipmap levels. The dst can have a writemask + which will specify what info is the caller interested + in. + RESINFO dst, src_mip_level, resource + e.g. + RESINFO TEMP[0], TEMP[1].x, RES[0] + src_mip_level is an unsigned integer scalar. If it's + out of range then returns 0 for width, height and + depth/array size but the total number of mipmap is + still returned correctly for the given resource. + The returned width, height and depth values are for + the mipmap level selected by the src_mip_level and + are in the number of texels. + For 1d texture array width is in dst.x, array size + is in dst.y and dst.zw are always 0. + +.. opcode:: SAMPLE_POS - query the position of a given sample. + dst receives float4 (x, y, 0, 0) indicated where the + sample is located. If the resource is not a multi-sample + resource and not a render target, the result is 0. + +.. opcode:: SAMPLE_INFO - dst receives number of samples in x. + If the resource is not a multi-sample resource and + not a render target, the result is 0. + + Explanation of symbols used ------------------------------ @@ -1332,6 +1483,8 @@ wrapping when interpolating by the rasteriser. If TGSI_CYLINDRICAL_WRAP_X is set to 1, the X component should be interpolated according to cylindrical wrapping rules. +If file is TGSI_FILE_RESOURCE, a Declaration Resource token follows. + Declaration Semantic ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1475,6 +1628,23 @@ is a writable stencil reference value. Only the Y component is writable. This allows the fragment shader to change the fragments stencilref value. +Declaration Resource +^^^^^^^^^^^^^^^^^^^^^^^^ + + Follows Declaration token if file is TGSI_FILE_RESOURCE. + + DCL RES[#], resource, type(s) + + Declares a shader input resource and assigns it to a RES[#] + register. + + resource can be one of BUFFER, 1D, 2D, 3D, CUBE, 1DArray and + 2DArray. + + type must be 1 or 4 entries (if specifying on a per-component + level) out of UNORM, SNORM, SINT, UINT and FLOAT. + + Properties ^^^^^^^^^^^^^^^^^^^^^^^^ |