diff options
author | Erik Faye-Lund <erik.faye-lund@collabora.com> | 2020-06-30 12:44:19 +0200 |
---|---|---|
committer | Marge Bot <eric+marge@anholt.net> | 2020-07-07 10:22:08 +0000 |
commit | 2f813981878614ce9567e981dbcaa1cd93dff187 (patch) | |
tree | 66cecf83b0d7a13d397dfbd2de3701a3d4ebee4e /docs/gallium/resources.rst | |
parent | cb11900cb6de9a2efdbb5924622859dafe35ac98 (diff) | |
download | external_mesa3d-2f813981878614ce9567e981dbcaa1cd93dff187.tar.gz external_mesa3d-2f813981878614ce9567e981dbcaa1cd93dff187.tar.bz2 external_mesa3d-2f813981878614ce9567e981dbcaa1cd93dff187.zip |
merge gallium docs into main docs
Reviewed-by: Eric Engestrom <eric@engestrom.ch>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/5706>
Diffstat (limited to 'docs/gallium/resources.rst')
-rw-r--r-- | docs/gallium/resources.rst | 207 |
1 files changed, 207 insertions, 0 deletions
diff --git a/docs/gallium/resources.rst b/docs/gallium/resources.rst new file mode 100644 index 00000000000..e3e15f85f3c --- /dev/null +++ b/docs/gallium/resources.rst @@ -0,0 +1,207 @@ +.. _resource: + +Resources and derived objects +============================= + +Resources represent objects that hold data: textures and buffers. + +They are mostly modelled after the resources in Direct3D 10/11, but with a +different transfer/update mechanism, and more features for OpenGL support. + +Resources can be used in several ways, and it is required to specify all planned uses through an appropriate set of bind flags. + +TODO: write much more on resources + +Transfers +--------- + +Transfers are the mechanism used to access resources with the CPU. + +OpenGL: OpenGL supports mapping buffers and has inline transfer functions for both buffers and textures + +D3D11: D3D11 lacks transfers, but has special resource types that are mappable to the CPU address space + +TODO: write much more on transfers + +Resource targets +---------------- + +Resource targets determine the type of a resource. + +Note that drivers may not actually have the restrictions listed regarding +coordinate normalization and wrap modes, and in fact efficient OpenCL +support will probably require drivers that don't have any of them, which +will probably be advertised with an appropriate cap. + +TODO: document all targets. Note that both 3D and cube have restrictions +that depend on the hardware generation. + + +PIPE_BUFFER +^^^^^^^^^^^ + +Buffer resource: can be used as a vertex, index, constant buffer +(appropriate bind flags must be requested). + +Buffers do not really have a format, it's just bytes, but they are required +to have their type set to a R8 format (without a specific "just byte" format, +R8_UINT would probably make the most sense, but for historic reasons R8_UNORM +is ok too). (This is just to make some shared buffer/texture code easier so +format size can be queried.) +width0 serves as size, most other resource properties don't apply but must be +set appropriately (depth0/height0/array_size must be 1, last_level 0). + +They can be bound to stream output if supported. +TODO: what about the restrictions lifted by the several later GL transform feedback extensions? How does one advertise that in Gallium? + +They can be also be bound to a shader stage (for sampling) as usual by +creating an appropriate sampler view, if the driver supports PIPE_CAP_TEXTURE_BUFFER_OBJECTS. +This supports larger width than a 1d texture would +(TODO limit currently unspecified, minimum must be at least 65536). +Only the "direct fetch" sample opcodes are supported (TGSI_OPCODE_TXF, +TGSI_OPCODE_SAMPLE_I) so the sampler state (coord wrapping etc.) +is mostly ignored (with SAMPLE_I there's no sampler state at all). + +They can be also be bound to the framebuffer (only as color render target, not +depth buffer, also there cannot be a depth buffer bound at the same time) as usual +by creating an appropriate view (this is not usable in OpenGL). +TODO there's no CAP bit currently for this, there's also unspecified size etc. limits +TODO: is there any chance of supporting GL pixel buffer object acceleration with this? + + +OpenGL: vertex buffers in GL 1.5 or GL_ARB_vertex_buffer_object + +- Binding to stream out requires GL 3.0 or GL_NV_transform_feedback +- Binding as constant buffers requires GL 3.1 or GL_ARB_uniform_buffer_object +- Binding to a sampling stage requires GL 3.1 or GL_ARB_texture_buffer_object + +D3D11: buffer resources +- Binding to a render target requires D3D_FEATURE_LEVEL_10_0 + +PIPE_TEXTURE_1D / PIPE_TEXTURE_1D_ARRAY +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +1D surface accessed with normalized coordinates. +1D array textures are supported depending on PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS. + +- If PIPE_CAP_NPOT_TEXTURES is not supported, + width must be a power of two +- height0 must be 1 +- depth0 must be 1 +- array_size must be 1 for PIPE_TEXTURE_1D +- Mipmaps can be used +- Must use normalized coordinates + +OpenGL: GL_TEXTURE_1D in GL 1.0 + +- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two + +D3D11: 1D textures in D3D_FEATURE_LEVEL_10_0 + +PIPE_TEXTURE_RECT +^^^^^^^^^^^^^^^^^ +2D surface with OpenGL GL_TEXTURE_RECTANGLE semantics. + +- depth0 must be 1 +- array_size must be 1 +- last_level must be 0 +- Must use unnormalized coordinates +- Must use a clamp wrap mode + +OpenGL: GL_TEXTURE_RECTANGLE in GL 3.1 or GL_ARB_texture_rectangle or GL_NV_texture_rectangle + +OpenCL: can create OpenCL images based on this, that can then be sampled arbitrarily + +D3D11: not supported (only PIPE_TEXTURE_2D with normalized coordinates is supported) + +PIPE_TEXTURE_2D / PIPE_TEXTURE_2D_ARRAY +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +2D surface accessed with normalized coordinates. +2D array textures are supported depending on PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS. + +- If PIPE_CAP_NPOT_TEXTURES is not supported, + width and height must be powers of two +- depth0 must be 1 +- array_size must be 1 for PIPE_TEXTURE_2D +- Mipmaps can be used +- Must use normalized coordinates +- No special restrictions on wrap modes + +OpenGL: GL_TEXTURE_2D in GL 1.0 + +- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two + +OpenCL: can create OpenCL images based on this, that can then be sampled arbitrarily + +D3D11: 2D textures + +- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_9_3 + +PIPE_TEXTURE_3D +^^^^^^^^^^^^^^^ + +3-dimensional array of texels. +Mipmap dimensions are reduced in all 3 coordinates. + +- If PIPE_CAP_NPOT_TEXTURES is not supported, + width, height and depth must be powers of two +- array_size must be 1 +- Must use normalized coordinates + +OpenGL: GL_TEXTURE_3D in GL 1.2 or GL_EXT_texture3D + +- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two + +D3D11: 3D textures + +- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_10_0 + +PIPE_TEXTURE_CUBE / PIPE_TEXTURE_CUBE_ARRAY +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Cube maps consist of 6 2D faces. +The 6 surfaces form an imaginary cube, and sampling happens by mapping an +input 3-vector to the point of the cube surface in that direction. +Cube map arrays are supported depending on PIPE_CAP_CUBE_MAP_ARRAY. + +Sampling may be optionally seamless if a driver supports it (PIPE_CAP_SEAMLESS_CUBE_MAP), +resulting in filtering taking samples from multiple surfaces near to the edge. + +- Width and height must be equal +- depth0 must be 1 +- array_size must be a multiple of 6 +- If PIPE_CAP_NPOT_TEXTURES is not supported, + width and height must be powers of two +- Must use normalized coordinates + +OpenGL: GL_TEXTURE_CUBE_MAP in GL 1.3 or EXT_texture_cube_map + +- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two +- Seamless cube maps require GL 3.2 or GL_ARB_seamless_cube_map or GL_AMD_seamless_cubemap_per_texture +- Cube map arrays require GL 4.0 or GL_ARB_texture_cube_map_array + +D3D11: 2D array textures with the D3D11_RESOURCE_MISC_TEXTURECUBE flag + +- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_10_0 +- Cube map arrays require D3D_FEATURE_LEVEL_10_1 + +Surfaces +-------- + +Surfaces are views of a resource that can be bound as a framebuffer to serve as the render target or depth buffer. + +TODO: write much more on surfaces + +OpenGL: FBOs are collections of surfaces in GL 3.0 or GL_ARB_framebuffer_object + +D3D11: render target views and depth/stencil views + +Sampler views +------------- + +Sampler views are views of a resource that can be bound to a pipeline stage to be sampled from shaders. + +TODO: write much more on sampler views + +OpenGL: texture objects are actually sampler view and resource in a single unit + +D3D11: shader resource views |