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