diff options
Diffstat (limited to 'src/gallium/docs/source')
| -rw-r--r-- | src/gallium/docs/source/context.rst | 125 | ||||
| -rw-r--r-- | src/gallium/docs/source/screen.rst | 3 | ||||
| -rw-r--r-- | src/gallium/docs/source/tgsi.rst | 239 |
3 files changed, 336 insertions, 31 deletions
diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index c33cf7c573..b0229c70f2 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 @@ -232,9 +244,16 @@ The most common type of query is the occlusion query, ``PIPE_QUERY_OCCLUSION_COUNTER``, which counts the number of fragments which 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. +The result is an unsigned 64-bit integer. Gallium does not guarantee the availability of any query types; one must always check the capabilities of the :ref:`Screen` first. @@ -347,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 @@ -357,6 +392,32 @@ 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)``. + + + +.. _texture_barrier + +texture_barrier +%%%%%%%%%%%%%%% + +This function flushes all pending writes to the currently-set surfaces and +invalidates all read caches of the currently-set samplers. + + + .. _pipe_transfer: PIPE_TRANSFER @@ -364,16 +425,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 09edbaa673..976e75bed0 100644 --- a/src/gallium/docs/source/screen.rst +++ b/src/gallium/docs/source/screen.rst @@ -36,6 +36,7 @@ The integer capabilities: bound. * ``OCCLUSION_QUERY``: Whether occlusion queries are available. * ``TIMER_QUERY``: Whether timer queries are available. +* ``INSTANCED_DRAWING``: indicates support for instanced drawing. * ``TEXTURE_SHADOW_MAP``: indicates whether the fragment shader hardware can do the depth texture / Z comparison operation in TEX instructions for shadow testing. @@ -272,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 d99ed7c6d6..4debcc6ecc 100644 --- a/src/gallium/docs/source/tgsi.rst +++ b/src/gallium/docs/source/tgsi.rst @@ -577,17 +577,45 @@ This instruction replicates its result. .. opcode:: TEX - Texture Lookup - TBD +.. math:: + + coord = src0 + + bias = 0.0 + + dst = texture_sample(unit, coord, bias) .. opcode:: TXD - Texture Lookup with Derivatives - TBD +.. math:: + + coord = src0 + + ddx = src1 + + ddy = src2 + + bias = 0.0 + + dst = texture_sample_deriv(unit, coord, bias, ddx, ddy) .. opcode:: TXP - Projective Texture Lookup - TBD +.. math:: + + coord.x = src0.x / src.w + + coord.y = src0.y / src.w + + coord.z = src0.z / src.w + + coord.w = src0.w + + bias = 0.0 + + dst = texture_sample(unit, coord, bias) .. opcode:: UP2H - Unpack Two 16-Bit Floats @@ -729,7 +757,19 @@ This instruction replicates its result. .. opcode:: TXB - Texture Lookup With Bias - TBD +.. math:: + + coord.x = src.x + + coord.y = src.y + + coord.z = src.z + + coord.w = 1.0 + + bias = src.z + + dst = texture_sample(unit, coord, bias) .. opcode:: NRM - 3-component Vector Normalise @@ -767,9 +807,21 @@ This instruction replicates its result. dst = src0.x \times src1.x + src0.y \times src1.y -.. opcode:: TXL - Texture Lookup With LOD +.. opcode:: TXL - Texture Lookup With explicit LOD - TBD +.. math:: + + coord.x = src0.x + + coord.y = src0.y + + coord.z = src0.z + + coord.w = 1.0 + + lod = src0.w + + dst = texture_sample(unit, coord, lod) .. opcode:: BRK - Break @@ -1198,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 ------------------------------ @@ -1280,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 ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1423,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 ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1464,6 +1686,11 @@ GL_ARB_fragment_coord_conventions extension. DirectX 9 uses INTEGER. DirectX 10 uses HALF_INTEGER. +FS_COLOR0_WRITES_ALL_CBUFS +"""""""""""""""""""""""""" +Specifies that writes to the fragment shader color 0 are replicated to all +bound cbufs. This facilitates OpenGL's fragColor output vs fragData[0] where +fragData is directed to a single color buffer, but fragColor is broadcast. Texture Sampling and Texture Formats |