diff options
Diffstat (limited to 'src/gallium/docs')
| -rw-r--r-- | src/gallium/docs/d3d11ddi.txt | 492 | ||||
| -rw-r--r-- | src/gallium/docs/source/context.rst | 41 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/blend.rst | 2 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/rasterizer.rst | 76 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/velems.rst | 24 |
5 files changed, 599 insertions, 36 deletions
diff --git a/src/gallium/docs/d3d11ddi.txt b/src/gallium/docs/d3d11ddi.txt new file mode 100644 index 0000000000..8f2509ce03 --- /dev/null +++ b/src/gallium/docs/d3d11ddi.txt @@ -0,0 +1,492 @@ +This document compares the D3D10/D3D11 device driver interface with Gallium. +It is written from the perspective of a developer implementing a D3D10/D3D11 driver as a Gallium state tracker. + +Note that naming and other cosmetic differences are not noted, since they don't really matter and would severely clutter the document. +Gallium/OpenGL terminology is used in preference to D3D terminology. + +NOTE: this document tries to be complete but most likely isn't fully complete and also not fully correct: please submit patches if you spot anything incorrect + +Also note that this is specifically for the DirectX 10/11 Windows Vista/7 DDI interfaces. +DirectX 9 has both user-mode (for Vista) and kernel mode (pre-Vista) interfaces, but they are significantly different from Gallium due to the presence of a lot of fixed function functionality. + +The user-visible DirectX 10/11 interfaces are distinct from the kernel DDI, but they match very closely. + +* Accessing Microsoft documentation + +See http://msdn.microsoft.com/en-us/library/dd445501.aspx ("D3D11DDI_DEVICEFUNCS") for D3D documentation. + +Also see http://download.microsoft.com/download/f/2/d/f2d5ee2c-b7ba-4cd0-9686-b6508b5479a1/direct3d10_web.pdf ("The Direct3D 10 System" by David Blythe) for an introduction to Direct3D 10 and the rationale for its design. + +The Windows Driver Kit contains the actual headers, as well as shader bytecode documentation. + +To get the headers from Linux, run the following, in a dedicated directory: +wget http://download.microsoft.com/download/4/A/2/4A25C7D5-EFBE-4182-B6A9-AE6850409A78/GRMWDK_EN_7600_1.ISO +sudo mount -o loop GRMWDK_EN_7600_1.ISO /mnt/tmp +cabextract -x /mnt/tmp/wdk/headers_cab001.cab +rename 's/^_(.*)_[0-9]*$/$1/' * +sudo umount /mnt/tmp + +d3d10umddi.h contains the DDI interface analyzed in this document: note that it is much easier to read this online on MSDN. +d3d{10,11}TokenizedProgramFormat.hpp contains the shader bytecode definitions: this is not available on MSDN. +d3d9types.h contains DX9 shader bytecode, and DX9 types +d3dumddi.h contains the DirectX 9 DDI interface + +* Glossary + +BC1: DXT1 +BC2: DXT3 +BC3: DXT5 +BC5: RGTC +BC6H: BPTC float +BC7: BPTC +CS = compute shader: OpenCL-like shader +DS = domain shader: tessellation evaluation shader +HS = hull shader: tessellation control shader +IA = input assembler: primitive assembly +Input layout: vertex elements +OM = output merger: blender +PS = pixel shader: fragment shader +Primitive topology: primitive type +Resource: buffer or texture +Shader resource (view): sampler view +SO = stream out: transform feedback +Unordered access view: view supporting random read/write access (usually from compute shaders) + +* Legend + +-: features D3D11 has and Gallium lacks ++: features Gallium has and D3D11 lacks +!: differences between D3D11 and Gallium +*: possible improvements to Gallium +>: references to comparisons of special enumerations +#: comment + +* Gallium functions with no direct D3D10/D3D11 equivalent + +clear + + Gallium supports clearing both render targets and depth/stencil with a single call + +draw_range_elements + + Gallium supports indexed draw with explicit range + +fence_signalled +fence_finish + + D3D10/D3D11 don't appear to support explicit fencing; queries can often substitute though, and flushing is supported + +set_clip_state + + Gallium supports fixed function user clip planes, D3D10/D3D11 only support using the vertex shader for them + +set_polygon_stipple + + Gallium supports polygon stipple + +surface_fill + + Gallium supports subrectangle fills of surfaces, D3D10 only supports full clears of views + +* DirectX 10/11 DDI functions and Gallium equivalents + +AbandonCommandList (D3D11 only) + - Gallium does not support deferred contexts + +CalcPrivateBlendStateSize +CalcPrivateDepthStencilStateSize +CalcPrivateDepthStencilViewSize +CalcPrivateElementLayoutSize +CalcPrivateGeometryShaderWithStreamOutput +CalcPrivateOpenedResourceSize +CalcPrivateQuerySize +CalcPrivateRasterizerStateSize +CalcPrivateRenderTargetViewSize +CalcPrivateResourceSize +CalcPrivateSamplerSize +CalcPrivateShaderResourceViewSize +CalcPrivateShaderSize +CalcDeferredContextHandleSize (D3D11 only) +CalcPrivateCommandListSize (D3D11 only) +CalcPrivateDeferredContextSize (D3D11 only) +CalcPrivateTessellationShaderSize (D3D11 only) +CalcPrivateUnorderedAccessViewSize (D3D11 only) + ! D3D11 allocates private objects itself, using the size computed here + * Gallium could do something similar to be able to put the private data inline into state tracker objects: this would allow them to fit in the same cacheline and improve performance + +CheckDeferredContextHandleSizes (D3D11 only) + - Gallium does not support deferred contexts + +CheckFormatSupport -> screen->is_format_supported + ! Gallium passes usages to this function, D3D11 returns them + - Gallium does not differentiate between blendable and non-blendable render targets + - Gallium lacks multisampled-texture and multisampled-render-target usages + +CheckMultisampleQualityLevels + * could merge this with is_format_supported + - Gallium lacks multisampling support + +CommandListExecute (D3D11 only) + - Gallium does not support command lists + +CopyStructureCount (D3D11 only) + - Gallium does not support unordered access views (views that can be written to arbitrarily from compute shaders) + +ClearDepthStencilView -> clear +ClearRenderTargetView -> clear + # D3D11 is not totally clear about whether this applies to any view or only a "currently-bound view" + + Gallium allows to clear both depth/stencil and render target(s) in a single operation + + Gallium supports double-precision depth values (but not rgba values!) + * May want to also support double-precision rgba or use "float" for "depth" + +ClearUnorderedAccessViewFloat (D3D11 only) +ClearUnorderedAccessViewUint (D3D11 only) + - Gallium does not support unordered access views (views that can be written to arbitrarily from compute shaders) + +CreateBlendState (extended in D3D10.1) -> create_blend_state + # D3D10 does not support per-RT blend modes (but per-RT blending), only D3D10.1 does + - Gallium lacks alpha-to-coverage + + Gallium supports logic ops + + Gallium supports dithering + + Gallium supports using the broadcast alpha component of the blend constant color + +CreateCommandList (D3D11 only) + - Gallium does not support command lists + +CreateComputeShader (D3D11 only) + - Gallium does not support compute shaders + +CreateDeferredContext (D3D11 only) + - Gallium does not support deferred contexts + +CreateDomainShader (D3D11 only) + - Gallium does not support domain shaders + +CreateHullShader (D3D11 only) + - Gallium does not support hull shaders + +CreateUnorderedAccessView (D3D11 only) + - Gallium does not support unordered access views + +CreateDepthStencilState -> create_depth_stencil_alpha_state + ! D3D11 has both a global stencil enable, and front/back enables; Gallium has only front/back enables + + Gallium has per-face writemask/valuemasks, D3D11 uses the same value for back and front + + Gallium supports the alpha test, which D3D11 lacks + +CreateDepthStencilView -> get_tex_surface +CreateRenderTargetView -> get_tex_surface + ! Gallium merges depthstencil and rendertarget views into pipe_surface, which also doubles as a 2D surface abstraction + - lack of texture array support + - lack of render-to-buffer support + + Gallium supports using 3D texture zslices as a depth/stencil buffer (in theory) + +CreateElementLayout -> create_vertex_elements_state + ! D3D11 allows sparse vertex elements (via InputRegister); in Gallium they must be specified sequentially + ! D3D11 has an extra flag (InputSlotClass) that is the same as instance_divisor == 0 + +CreateGeometryShader -> create_gs_state +CreateGeometryShaderWithStreamOutput -> create_gs_state +CreatePixelShader -> create_fs_state +CreateVertexShader -> create_vs_state + > bytecode is different (see D3d10tokenizedprogramformat.hpp) + ! D3D11 describes input/outputs separately from bytecode; Gallium has the tgsi_scan.c module to extract it from TGSI + @ TODO: look into DirectX 10/11 semantics specification and bytecode + +CheckCounter +CheckCounterInfo +CreateQuery -> create_query + - Gallium only supports occlusion, primitives generated and primitives emitted queries + ! D3D11 implements fences with "event" queries + * TIMESTAMP could be implemented as an additional fields for other queries: some cards have hardware support for exactly this + * OCCLUSIONPREDICATE is required for the OpenGL v2 occlusion query functionality + * others are performance counters, we may want them but they are not critical + +CreateRasterizerState + - Gallium lacks clamping of polygon offset depth biases + - Gallium lacks support to disable depth clipping + - Gallium lacks multisampling + + Gallium, like OpenGL, supports PIPE_POLYGON_MODE_POINT + + Gallium, like OpenGL, supports per-face polygon fill modes + + Gallium, like OpenGL, supports culling everything + + Gallium, like OpenGL, supports two-side lighting; D3D11 only has the facing attribute + + Gallium, like OpenGL, supports per-fill-mode polygon offset enables + + Gallium, like OpenGL, supports polygon smoothing + + Gallium, like OpenGL, supports polygon stipple + + Gallium, like OpenGL, supports point smoothing + + Gallium, like OpenGL, supports point sprites + + Gallium supports specifying point quad rasterization + + Gallium, like OpenGL, supports per-point point size + + Gallium, like OpenGL, supports line smoothing + + Gallium, like OpenGL, supports line stipple + + Gallium supports line last pixel rule specification + + Gallium, like OpenGL, supports provoking vertex convention + + Gallium supports D3D9 rasterization rules + + Gallium supports fixed line width + + Gallium supports fixed point size + +CreateResource -> texture_create or buffer_create + ! D3D11 passes the dimensions of all mipmap levels to the create call, while Gallium has an implicit floor(x/2) rule + # Note that hardware often has the implicit rule, so the D3D11 interface seems to make little sense + # Also, the D3D11 API does not allow the user to specify mipmap sizes, so this really seems a dubious decision on Microsoft's part + - D3D11 supports specifying initial data to write in the resource + - Gallium lacks support for stream output buffer usage + - Gallium does not support unordered access buffers + ! D3D11 specifies mapping flags (i.e. read/write/discard);:it's unclear what they are used for here + - D3D11 supports odd things in the D3D10_DDI_RESOURCE_MISC_FLAG enum (D3D10_DDI_RESOURCE_MISC_DISCARD_ON_PRESENT, D3D11_DDI_RESOURCE_MISC_BUFFER_ALLOW_RAW_VIEWS, D3D11_DDI_RESOURCE_MISC_BUFFER_STRUCTURED) + - Gallium does not support indirect draw call parameter buffers + - Gallium lacks multisampling + - Gallium lacks array textures + ! D3D11 supports specifying hardware modes and other stuff here for scanout resources + + Gallium allows specifying minimum buffer alignment + ! D3D11 implements cube maps as 2D array textures + +CreateSampler + - D3D11 supports a monochrome convolution filter for "text filtering" + + Gallium supports non-normalized coordinates + + Gallium supports CLAMP, MIRROR_CLAMP and MIRROR_CLAMP_TO_BORDER + + Gallium supports setting min/max/mip filters and anisotropy independently + +CreateShaderResourceView (extended in D3D10.1) -> create_sampler_view + - Gallium lacks sampler views over buffers + - Gallium lacks texture arrays, and cube map views over texture arrays + + Gallium supports specifying a swizzle + ! D3D11 implements "cube views" as views into a 2D array texture + +CsSetConstantBuffers (D3D11 only) +CsSetSamplers (D3D11 only) +CsSetShader (D3D11 only) +CsSetShaderResources (D3D11 only) +CsSetShaderWithIfaces (D3D11 only) +CsSetUnorderedAccessViews (D3D11 only) + - Gallium does not support compute shaders + +DestroyBlendState +DestroyCommandList (D3D11 only) +DestroyDepthStencilState +DestroyDepthStencilView +DestroyDevice +DestroyElementLayout +DestroyQuery +DestroyRasterizerState +DestroyRenderTargetView +DestroyResource +DestroySampler +DestroyShader +DestroyShaderResourceView +DestroyUnorderedAccessView (D3D11 only) + # these are trivial + +Dispatch (D3D11 only) + - Gallium does not support compute shaders + +DispatchIndirect (D3D11 only) + - Gallium does not support compute shaders + +Draw -> draw_arrays + ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better + +DrawAuto + - Gallium lacks stream out and DrawAuto + +DrawIndexed -> draw_elements + ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better + * may want to add a separate set_index_buffer + - Gallium lacks base vertex for indexed draw calls + + D3D11 lacks draw_range_elements functionality, which is required for OpenGL + +DrawIndexedInstanced -> draw_elements_instanced + ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better + * may want to add a separate set_index_buffer + - Gallium lacks base vertex for indexed draw calls + +DrawIndexedInstancedIndirect (D3D11 only) -> call draw_elements_instanced multiple times in software + # this allows to use an hardware buffer to specify the parameters for multiple draw_elements_instanced calls + - Gallium does not support draw call parameter buffers and indirect draw + +DrawInstanced -> draw_arrays_instanced + ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better + +DrawInstancedIndirect (D3D11 only) -> call draw_arrays_instanced multiple times in software + # this allows to use an hardware buffer to specify the parameters for multiple draw_arrays_instanced calls + - Gallium does not support draw call parameter buffers and indirect draws + +DsSetConstantBuffers (D3D11 only) +DsSetSamplers (D3D11 only) +DsSetShader (D3D11 only) +DsSetShaderResources (D3D11 only) +DsSetShaderWithIfaces (D3D11 only) + - Gallium does not support domain shaders + +Flush -> flush + ! Gallium supports fencing and several kinds of flushing here, D3D11 just has a dumb glFlush-like function + +GenMips + - Gallium lacks a mipmap generation interface, and does this manually with the 3D engine + * it may be useful to add a mipmap generation interface, since the hardware (especially older cards) may have a better way than using the 3D engine + +GsSetConstantBuffers -> for(i = StartBuffer; i < NumBuffers; ++i) set_constant_buffer(PIPE_SHADER_GEOMETRY, i, phBuffers[i]) + +GsSetSamplers + - Gallium does not support sampling in geometry shaders + +GsSetShader -> bind_gs_state + +GsSetShaderWithIfaces (D3D11 only) + - Gallium does not support shader interfaces + +GsSetShaderResources + - Gallium does not support sampling in geometry shaders + +HsSetConstantBuffers (D3D11 only) +HsSetSamplers (D3D11 only) +HsSetShader (D3D11 only) +HsSetShaderResources (D3D11 only) +HsSetShaderWithIfaces (D3D11 only) + - Gallium does not support hull shaders + +IaSetIndexBuffer + ! Gallium passes this to the draw_elements or draw_elements_instanced calls + + Gallium supports 8-bit indices + ! the D3D11 interface allows index-size-unaligned byte offsets into index buffers; it's not clear whether they actually work + +IaSetInputLayout -> bind_vertex_elements_state + +IaSetTopology + ! Gallium passes the topology = primitive type to the draw calls + * may want to add an interface for this + - Gallium lacks support for DirectX 11 tessellated primitives + + 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 + +PsSetConstantBuffers -> for(i = StartBuffer; i < NumBuffers; ++i) set_constant_buffer(PIPE_SHADER_FRAGMENT, i, phBuffers[i]) + * may want to split into fragment/vertex-specific versions + +PsSetSamplers -> bind_fragment_sampler_states + * may want to allow binding subsets instead of all at once + +PsSetShader -> bind_fs_state + +PsSetShaderWithIfaces (D3D11 only) + - Gallium does not support shader interfaces + +PsSetShaderResources -> set_fragment_sampler_views + * may want to allow binding subsets instead of all at once + +QueryBegin -> begin_query + +QueryEnd -> end_query + +QueryGetData -> get_query_result + - D3D11 supports reading an arbitrary data chunk for query results, Gallium only supports reading a 64-bit integer + + D3D11 doesn't seem to support actually waiting for the query result (?!) + - D3D11 supports optionally not flushing command buffers here and instead returning DXGI_DDI_ERR_WASSTILLDRAWING + +RecycleCommandList (D3D11 only) +RecycleCreateCommandList (D3D11 only) +RecycleDestroyCommandList (D3D11 only) + - Gallium does not support command lists + +RecycleCreateDeferredContext (D3D11 only) + - Gallium does not support deferred contexts + +RelocateDeviceFuncs + - Gallium does not support moving pipe_context, while D3D11 seems to, using this + +ResetPrimitiveID (D3D10.1+ only, #ifdef D3D10PSGP) + # used to do vertex processing on the GPU on Intel G45 chipsets when it is faster this way (see www.intel.com/Assets/PDF/whitepaper/322931.pdf) + # presumably this resets the primitive id system value + - Gallium does not support vertex pipeline bypass anymore + +ResourceCopy +ResourceCopyRegion +ResourceConvert (D3D10.1+ only) +ResourceConvertRegion (D3D10.1+ only) + -> surface_copy + - Gallium does not support hardware buffer copies + - Gallium does not support copying 3D texture subregions in a single call + +ResourceIsStagingBusy -> is_texture_referenced, is_buffer_referenced + - Gallium does not support checking reference for a whole texture, but only a specific surface + +ResourceReadAfterWriteHazard + ! Gallium specifies hides this, except for the render and texture caches + +ResourceResolveSubresource + - Gallium does not support multisample sample resolution + +ResourceMap +ResourceUnmap +DynamicConstantBufferMapDiscard +DynamicConstantBufferUnmap +DynamicIABufferMapDiscard +DynamicIABufferMapNoOverwrite +DynamicIABufferUnmap +DynamicResourceMapDiscard +DynamicResourceUnmap +StagingResourceMap +StagingResourceUnmap + -> buffer_map / buffer_unmap + -> transfer functions + ! Gallium and D3D have different semantics for transfers + * D3D separates vertex/index buffers from constant buffers + ! D3D separates some buffer flags into specialized calls + +ResourceUpdateSubresourceUP -> transfer functionality, transfer_inline_write in gallium-resources +DefaultConstantBufferUpdateSubresourceUP -> transfer functionality, transfer_inline_write in gallium-resources + +SetBlendState -> bind_blend_state and set_blend_color + ! D3D11 fuses bind_blend_state and set_blend_color in a single function + - Gallium lacks the sample mask + +SetDepthStencilState -> bind_depth_stencil_alpha_state and set_stencil_ref + ! D3D11 fuses bind_depth_stencil_alpha_state and set_stencil_ref in a single function + +SetPredication -> render_condition + # here both D3D11 and Gallium seem very limited (hardware is too, probably though) + # ideally, we should support nested conditional rendering, as well as more complex tests (checking for an arbitrary range, after an AND with arbitrary mask ) + # of couse, hardware support is probably as limited as OpenGL/D3D11 + + Gallium, like NV_conditional_render, supports by-region and wait flags + - D3D11 supports predication conditional on being equal any value (along with occlusion predicates); Gallium only supports on non-zero + +SetRasterizerState -> bind_rasterizer_state + +SetRenderTargets (extended in D3D11) -> set_framebuffer_state + ! Gallium passed a width/height here, D3D11 does not + ! Gallium lacks ClearTargets (but this is redundant and the driver can trivially compute this if desired) + - Gallium does not support unordered access views + - Gallium does not support geometry shader selection of texture array image / 3D texture zslice + +SetResourceMinLOD (D3D11 only) + - Gallium does not support min lod directly on textures + +SetScissorRects + - Gallium lacks support for multiple geometry-shader-selectable scissor rectangles D3D11 has + +SetTextFilterSize + - Gallium lacks support for text filters + +SetVertexPipelineOutput (D3D10.1+ only) + # used to do vertex processing on the GPU on Intel G45 chipsets when it is faster this way (see www.intel.com/Assets/PDF/whitepaper/322931.pdf) + - Gallium does not support vertex pipeline bypass anymore + +SetViewports + - Gallium lacks support for multiple geometry-shader-selectable viewports D3D11 has + +ShaderResourceViewReadAfterWriteHazard -> flush(PIPE_FLUSH_RENDER_CACHE) + - Gallium does not support specifying this per-render-target/view + +SoSetTargets + - Gallium does not support stream out + +VsSetConstantBuffers -> for(i = StartBuffer; i < NumBuffers; ++i) set_constant_buffer(PIPE_SHADER_VERTEX, i, phBuffers[i]) + * may want to split into fragment/vertex-specific versions + +VsSetSamplers -> bind_vertex_sampler_states + * may want to allow binding subsets instead of all at once + +VsSetShader -> bind_vs_state + +VsSetShaderWithIfaces (D3D11 only) + - Gallium does not support shader interfaces + +VsSetShaderResources -> set_fragment_sampler_views + * may want to allow binding subsets instead of all at once diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index 9080addba4..2b0941010b 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -24,6 +24,7 @@ CSO objects handled by the context object: * :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:`Vertex Elements`: ``*_vertex_elements_state`` Resource Binding State @@ -39,8 +40,7 @@ buffers, surfaces) are bound to the driver. are mostly restricted to the first one right now). * ``set_framebuffer_state`` -* ``set_fragment_sampler_textures`` -* ``set_vertex_sampler_textures`` + * ``set_vertex_buffers`` @@ -50,6 +50,7 @@ Non-CSO State These pieces of state are too small, variable, and/or trivial to have CSO objects. They all follow simple, one-method binding calls, e.g. ``set_blend_color``. + * ``set_stencil_ref`` sets the stencil front and back reference values which are used as comparison values in stencil test. * ``set_blend_color`` @@ -60,7 +61,41 @@ objects. They all follow simple, one-method binding calls, e.g. not have the scissor test enabled, then the scissor bounds never need to be set since they will not be used. * ``set_viewport_state`` -* ``set_vertex_elements`` + + +Sampler Views +^^^^^^^^^^^^^ + +These are the means to bind textures to shader stages. To create one, specify +its format, swizzle and LOD range in sampler view template. + +If texture format is different than template format, it is said the texture +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 +in the result register. For example, ``swizzle_r`` specifies what is going to be +placed in first component of result register. + +The ``first_level`` and ``last_level`` fields of sampler view template specify +the LOD range the texture is going to be constrained to. + +* ``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. + +* ``set_vertex_sampler_views`` binds an array of sampler views to vertex + shader stage. Every binding point acquires a reference to a respective + sampler view and releases a reference to the previous sampler view. + +* ``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 + with texture format. + +* ``sampler_view_destroy`` destroys a sampler view and releases its reference + to associated texture. Clearing diff --git a/src/gallium/docs/source/cso/blend.rst b/src/gallium/docs/source/cso/blend.rst index 55c0f32885..c74396284c 100644 --- a/src/gallium/docs/source/cso/blend.rst +++ b/src/gallium/docs/source/cso/blend.rst @@ -28,7 +28,7 @@ logicop_enable logicop_func The logic operation to use if logic ops are enabled. One of PIPE_LOGICOP. dither - Whether dithering is enabled. + Whether dithering is enabled. Note: Dithering is implementation-dependent. rt Contains the per-rendertarget blend state. diff --git a/src/gallium/docs/source/cso/rasterizer.rst b/src/gallium/docs/source/cso/rasterizer.rst index ccd9136a2e..56a601a8d0 100644 --- a/src/gallium/docs/source/cso/rasterizer.rst +++ b/src/gallium/docs/source/cso/rasterizer.rst @@ -7,7 +7,7 @@ The rasterizer state controls the rendering of points, lines and triangles. Attributes include polygon culling state, line width, line stipple, multisample state, scissoring and flat/smooth shading. -Members +Shading ------- flatshade @@ -46,6 +46,49 @@ There are several important exceptions to the specification of this rule. second vertex, not the first. This permits each segment of the fan to have a different color. +Points +------ + +sprite_coord_enable +^^^^^^^^^^^^^^^^^^^ + +Specifies if a texture unit has its texture coordinates replaced or not. This +is a packed bitfield containing the enable for all texcoords -- if all bits +are zero, point sprites are effectively disabled. If any bit is set, then +point_smooth and point_quad_rasterization are ignored; point smoothing is +disabled and points are always rasterized as quads. If enabled, the four +vertices of the resulting quad will be assigned texture coordinates, +according to sprite_coord_mode. + +sprite_coord_mode +^^^^^^^^^^^^^^^^^ + +Specifies how the value for each shader output should be computed when drawing +point sprites. For PIPE_SPRITE_COORD_LOWER_LEFT, the lower-left vertex will +have coordinates (0,0,0,1). For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left +vertex will have coordinates (0,0,0,1). +This state is used by :ref:`Draw` to generate texcoords. + +.. note:: + + When geometry shaders are available, a special geometry shader could be + used instead of this functionality, to convert incoming points into quads + with the proper texture coordinates. + +point_quad_rasterization +^^^^^^^^^^^^^^^^^^^^^^^^ + +Determines if points should be rasterized as quads or points. Certain APIs, +like Direct3D, always use quad rasterization for points, regardless of +whether point sprites are enabled or not. If this state is enabled, point +smoothing and antialiasing are disabled. If it is disabled, point sprite +coordinates are not generated. + +.. note:: + + Some renderers always internally translate points into quads; this state + still affects those renderers by overriding other rasterization state. + Other Members ^^^^^^^^^^^^^ @@ -107,37 +150,6 @@ point_size_per_vertex Whether vertices have a point size element. point_size The size of points, if not specified per-vertex. -sprite_coord_enable - Specifies if a coord has its texture coordinates replaced or not. This - is a packed bitfield containing the enable for all coords - if all are 0 - point sprites are effectively disabled, though points may still be - rendered slightly different according to point_quad_rasterization. - If any coord is non-zero, point_smooth should be disabled, and - point_quad_rasterization enabled. - If enabled, the four vertices of the resulting quad will be assigned - texture coordinates, according to sprite_coord_mode. -sprite_coord_mode - Specifies how the value for each shader output should be computed when - drawing sprites, for each coord which has sprite_coord_enable set. - For PIPE_SPRITE_COORD_LOWER_LEFT, the lower left vertex will have - coordinate (0,0,0,1). - For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left vertex will have - coordinate (0,0,0,1). - This state is needed by :ref:`Draw` because that's where each - point vertex is converted into four quad vertices. There's no other - place to emit the new vertex texture coordinates which are required for - sprite rendering. - Note that when geometry shaders are available, this state could be - removed. A special geometry shader defined by the state tracker could - convert the incoming points into quads with the proper texture coords. -point_quad_rasterization - This determines if points should be rasterized as quads or points. - d3d always uses quad rasterization for points, regardless if point sprites - are enabled or not, but OGL has different rules. If point_quad_rasterization - is set, point_smooth should be disabled, and points will be rendered as - squares even if multisample is enabled. - sprite_coord_enable should be zero if point_quad_rasterization is not - enabled. scissor Whether the scissor test is enabled. diff --git a/src/gallium/docs/source/cso/velems.rst b/src/gallium/docs/source/cso/velems.rst new file mode 100644 index 0000000000..92cde014fb --- /dev/null +++ b/src/gallium/docs/source/cso/velems.rst @@ -0,0 +1,24 @@ +.. _vertexelements: + +Vertex Elements +=============== + +This state controls format etc. of the input attributes contained +in the pipe_vertex_buffer(s). There's one pipe_vertex_element array member +for each input attribute. + +Members +------- + +src_offset + The byte offset of the attribute in the buffer given by + vertex_buffer_index for the first vertex. +instance_divisor + The instance data rate divisor, used for instancing. + 0 means this is per-vertex data, n means per-instance data used for + n consecutive instances (n > 0). +vertex_buffer_index + The vertex buffer this attribute lives in. Several attributes may + live in the same vertex buffer. +src_format + The format of the attribute data. One of the PIPE_FORMAT tokens. |