1.. _resource: 2 3Resources and derived objects 4============================= 5 6Resources represent objects that hold data: textures and buffers. 7 8They are mostly modelled after the resources in Direct3D 10/11, but with a 9different transfer/update mechanism, and more features for OpenGL support. 10 11Resources can be used in several ways, and it is required to specify all planned uses through an appropriate set of bind flags. 12 13TODO: write much more on resources 14 15Transfers 16--------- 17 18Transfers are the mechanism used to access resources with the CPU. 19 20OpenGL: OpenGL supports mapping buffers and has inline transfer functions for both buffers and textures 21 22D3D11: D3D11 lacks transfers, but has special resource types that are mappable to the CPU address space 23 24TODO: write much more on transfers 25 26Resource targets 27---------------- 28 29Resource targets determine the type of a resource. 30 31Note that drivers may not actually have the restrictions listed regarding 32coordinate normalization and wrap modes, and in fact efficient OpenCL 33support will probably require drivers that don't have any of them, which 34will probably be advertised with an appropriate cap. 35 36TODO: document all targets. Note that both 3D and cube have restrictions 37that depend on the hardware generation. 38 39 40PIPE_BUFFER 41^^^^^^^^^^^ 42 43Buffer resource: can be used as a vertex, index, constant buffer 44(appropriate bind flags must be requested). 45 46Buffers do not really have a format, it's just bytes, but they are required 47to have their type set to a R8 format (without a specific "just byte" format, 48R8_UINT would probably make the most sense, but for historic reasons R8_UNORM 49is OK too). (This is just to make some shared buffer/texture code easier so 50format size can be queried.) 51width0 serves as size, most other resource properties don't apply but must be 52set appropriately (depth0/height0/array_size must be 1, last_level 0). 53 54They can be bound to stream output if supported. 55TODO: what about the restrictions lifted by the several later GL transform feedback extensions? How does one advertise that in Gallium? 56 57They can be also be bound to a shader stage (for sampling) as usual by 58creating an appropriate sampler view, if the driver supports PIPE_CAP_TEXTURE_BUFFER_OBJECTS. 59This supports larger width than a 1d texture would 60(TODO limit currently unspecified, minimum must be at least 65536). 61Only the "direct fetch" sample opcodes are supported (TGSI_OPCODE_TXF, 62TGSI_OPCODE_SAMPLE_I) so the sampler state (coord wrapping etc.) 63is mostly ignored (with SAMPLE_I there's no sampler state at all). 64 65They can be also be bound to the framebuffer (only as color render target, not 66depth buffer, also there cannot be a depth buffer bound at the same time) as usual 67by creating an appropriate view (this is not usable in OpenGL). 68TODO there's no CAP bit currently for this, there's also unspecified size etc. limits 69TODO: is there any chance of supporting GL pixel buffer object acceleration with this? 70 71 72OpenGL: vertex buffers in GL 1.5 or :ext:`GL_ARB_vertex_buffer_object` 73 74- Binding to stream out requires GL 3.0 or :ext:`GL_NV_transform_feedback` 75- Binding as constant buffers requires GL 3.1 or :ext:`GL_ARB_uniform_buffer_object` 76- Binding to a sampling stage requires GL 3.1 or :ext:`GL_ARB_texture_buffer_object` 77 78D3D11: buffer resources 79- Binding to a render target requires D3D_FEATURE_LEVEL_10_0 80 81PIPE_TEXTURE_1D / PIPE_TEXTURE_1D_ARRAY 82^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 831D surface accessed with normalized coordinates. 841D array textures are supported depending on PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS. 85 86- If PIPE_CAP_NPOT_TEXTURES is not supported, 87 width must be a power of two 88- height0 must be 1 89- depth0 must be 1 90- array_size must be 1 for PIPE_TEXTURE_1D 91- Mipmaps can be used 92- Must use normalized coordinates 93 94OpenGL: GL_TEXTURE_1D in GL 1.0 95 96- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or :ext:`GL_ARB_texture_non_power_of_two` 97 98D3D11: 1D textures in D3D_FEATURE_LEVEL_10_0 99 100PIPE_TEXTURE_RECT 101^^^^^^^^^^^^^^^^^ 1022D surface with OpenGL GL_TEXTURE_RECTANGLE semantics. 103 104- depth0 must be 1 105- array_size must be 1 106- last_level must be 0 107- Must use unnormalized coordinates 108- Must use a clamp wrap mode 109 110OpenGL: GL_TEXTURE_RECTANGLE in GL 3.1 or :ext:`GL_ARB_texture_rectangle` or 111:ext:`GL_NV_texture_rectangle` 112 113OpenCL: can create OpenCL images based on this, that can then be sampled arbitrarily 114 115D3D11: not supported (only PIPE_TEXTURE_2D with normalized coordinates is supported) 116 117PIPE_TEXTURE_2D / PIPE_TEXTURE_2D_ARRAY 118^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1192D surface accessed with normalized coordinates. 1202D array textures are supported depending on PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS. 121 122- If PIPE_CAP_NPOT_TEXTURES is not supported, 123 width and height must be powers of two 124- depth0 must be 1 125- array_size must be 1 for PIPE_TEXTURE_2D 126- Mipmaps can be used 127- Must use normalized coordinates 128- No special restrictions on wrap modes 129 130OpenGL: GL_TEXTURE_2D in GL 1.0 131 132- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or :ext:`GL_ARB_texture_non_power_of_two` 133 134OpenCL: can create OpenCL images based on this, that can then be sampled arbitrarily 135 136D3D11: 2D textures 137 138- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_9_3 139 140PIPE_TEXTURE_3D 141^^^^^^^^^^^^^^^ 142 1433-dimensional array of texels. 144Mipmap dimensions are reduced in all 3 coordinates. 145 146- If PIPE_CAP_NPOT_TEXTURES is not supported, 147 width, height and depth must be powers of two 148- array_size must be 1 149- Must use normalized coordinates 150 151OpenGL: GL_TEXTURE_3D in GL 1.2 or :ext:`GL_EXT_texture3D` 152 153- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or :ext:`GL_ARB_texture_non_power_of_two` 154 155D3D11: 3D textures 156 157- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_10_0 158 159PIPE_TEXTURE_CUBE / PIPE_TEXTURE_CUBE_ARRAY 160^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 161 162Cube maps consist of 6 2D faces. 163The 6 surfaces form an imaginary cube, and sampling happens by mapping an 164input 3-vector to the point of the cube surface in that direction. 165Cube map arrays are supported depending on PIPE_CAP_CUBE_MAP_ARRAY. 166 167Sampling may be optionally seamless if a driver supports it (PIPE_CAP_SEAMLESS_CUBE_MAP), 168resulting in filtering taking samples from multiple surfaces near to the edge. 169 170- Width and height must be equal 171- depth0 must be 1 172- array_size must be a multiple of 6 173- If PIPE_CAP_NPOT_TEXTURES is not supported, 174 width and height must be powers of two 175- Must use normalized coordinates 176 177OpenGL: GL_TEXTURE_CUBE_MAP in GL 1.3 or :ext:`GL_EXT_texture_cube_map` 178 179- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or :ext:`GL_ARB_texture_non_power_of_two` 180- Seamless cube maps require GL 3.2 or :ext:`GL_ARB_seamless_cube_map` or :ext:`GL_AMD_seamless_cubemap_per_texture` 181- Cube map arrays require GL 4.0 or :ext:`GL_ARB_texture_cube_map_array` 182 183D3D11: 2D array textures with the D3D11_RESOURCE_MISC_TEXTURECUBE flag 184 185- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_10_0 186- Cube map arrays require D3D_FEATURE_LEVEL_10_1 187 188Surfaces 189-------- 190 191Surfaces are views of a resource that can be bound as a framebuffer to serve as the render target or depth buffer. 192 193TODO: write much more on surfaces 194 195OpenGL: FBOs are collections of surfaces in GL 3.0 or :ext:`GL_ARB_framebuffer_object` 196 197D3D11: render target views and depth/stencil views 198 199Sampler views 200------------- 201 202Sampler views are views of a resource that can be bound to a pipeline stage to be sampled from shaders. 203 204TODO: write much more on sampler views 205 206OpenGL: texture objects are actually sampler view and resource in a single unit 207 208D3D11: shader resource views 209