1Resources and derived objects 2============================= 3 4Resources represent objects that hold data: textures and buffers. 5 6They are mostly modelled after the resources in Direct3D 10/11, but with a 7different transfer/update mechanism, and more features for OpenGL support. 8 9Resources can be used in several ways, and it is required to specify all planned uses through an appropriate set of bind flags. 10 11TODO: write much more on resources 12 13Transfers 14--------- 15 16Transfers are the mechanism used to access resources with the CPU. 17 18OpenGL: OpenGL supports mapping buffers and has inline transfer functions for both buffers and textures 19 20D3D11: D3D11 lacks transfers, but has special resource types that are mappable to the CPU address space 21 22TODO: write much more on transfers 23 24Resource targets 25---------------- 26 27Resource targets determine the type of a resource. 28 29Note that drivers may not actually have the restrictions listed regarding 30coordinate normalization and wrap modes, and in fact efficient OpenCL 31support will probably require drivers that don't have any of them, which 32will probably be advertised with an appropriate cap. 33 34TODO: document all targets. Note that both 3D and cube have restrictions 35that depend on the hardware generation. 36 37TODO: can buffers have a non-R8 format? 38 39PIPE_BUFFER 40^^^^^^^^^^^ 41 42Buffer resource: can be used as a vertex, index, constant buffer (appropriate bind flags must be requested). 43 44They can be bound to stream output if supported. 45TODO: what about the restrictions lifted by the several later GL transform feedback extensions? How does one advertise that in Gallium? 46 47They can be also be bound to a shader stage as usual. 48TODO: are all drivers supposed to support this? how does this work exactly? are there size limits? 49 50They can be also be bound to the framebuffer as usual. 51TODO: are all drivers supposed to support this? how does this work exactly? are there size limits? 52TODO: is there any chance of supporting GL pixel buffer object acceleration with this? 53 54- depth0 must be 1 55- last_level must be 0 56- TODO: what about normalization? 57- TODO: wrap modes/other sampling state? 58- TODO: are arbitrary formats supported? in which cases? 59 60OpenGL: vertex buffers in GL 1.5 or GL_ARB_vertex_buffer_object 61 62- Binding to stream out requires GL 3.0 or GL_NV_transform_feedback 63- Binding as constant buffers requires GL 3.1 or GL_ARB_uniform_buffer_object 64- Binding to a sampling stage requires GL 3.1 or GL_ARB_texture_buffer_object 65- TODO: can they be bound to an FBO? 66 67D3D11: buffer resources 68- Binding to a render target requires D3D_FEATURE_LEVEL_10_0 69 70PIPE_TEXTURE_1D 71^^^^^^^^^^^^^^^ 721D surface accessed with normalized coordinates. 73 74UNIMPLEMENTED: 1D texture arrays not supported 75 76- If PIPE_CAP_NPOT_TEXTURES is not supported, 77 width must be a power of two 78- height0 must be 1 79- depth0 must be 1 80- Mipmaps can be used 81- Must use normalized coordinates 82 83OpenGL: GL_TEXTURE_1D in GL 1.0 84 85- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two 86 87D3D11: 1D textures in D3D_FEATURE_LEVEL_10_0 88 89PIPE_TEXTURE_RECT 90^^^^^^^^^^^^^^^^^ 912D surface with OpenGL GL_TEXTURE_RECTANGLE semantics. 92 93- depth0 must be 1 94- last_level must be 0 95- Must use unnormalized coordinates 96- Must use a clamp wrap mode 97 98OpenGL: GL_TEXTURE_RECTANGLE in GL 3.1 or GL_ARB_texture_rectangle or GL_NV_texture_rectangle 99 100OpenCL: can create OpenCL images based on this, that can then be sampled arbitrarily 101 102D3D11: not supported (only PIPE_TEXTURE_2D with normalized coordinates is supported) 103 104PIPE_TEXTURE_2D 105^^^^^^^^^^^^^^^ 1062D surface accessed with normalized coordinates. 107 108UNIMPLEMENTED: 2D texture arrays not supported 109 110- If PIPE_CAP_NPOT_TEXTURES is not supported, 111 width and height must be powers of two 112- depth0 must be 1 113- Mipmaps can be used 114- Must use normalized coordinates 115- No special restrictions on wrap modes 116 117OpenGL: GL_TEXTURE_2D in GL 1.0 118 119- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two 120 121OpenCL: can create OpenCL images based on this, that can then be sampled arbitrarily 122 123D3D11: 2D textures 124 125- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_9_3 126 127PIPE_TEXTURE_3D 128^^^^^^^^^^^^^^^ 129 1303-dimensional array of texels. 131Mipmap dimensions are reduced in all 3 coordinates. 132 133- If PIPE_CAP_NPOT_TEXTURES is not supported, 134 width, height and depth must be powers of two 135- Must use normalized coordinates 136 137OpenGL: GL_TEXTURE_3D in GL 1.2 or GL_EXT_texture3D 138 139- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two 140 141D3D11: 3D textures 142 143- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_10_0 144 145PIPE_TEXTURE_CUBE 146^^^^^^^^^^^^^^^^^ 147 148Cube maps consist of 6 2D faces. 149The 6 surfaces form an imaginary cube, and sampling happens by mapping an 150input 3-vector to the point of the cube surface in that direction. 151 152Sampling may be optionally seamless, resulting in filtering taking samples 153from multiple surfaces near to the edge. 154UNIMPLEMENTED: seamless cube map sampling not supported 155 156UNIMPLEMENTED: cube map arrays not supported 157 158- Width and height must be equal 159- If PIPE_CAP_NPOT_TEXTURES is not supported, 160 width and height must be powers of two 161- Must use normalized coordinates 162 163OpenGL: GL_TEXTURE_CUBE_MAP in GL 1.3 or EXT_texture_cube_map 164 165- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two 166- Seamless cube maps require GL 3.2 or GL_ARB_seamless_cube_map or GL_AMD_seamless_cubemap_per_texture 167- Cube map arrays require GL 4.0 or GL_ARB_texture_cube_map_array 168 169D3D11: 2D array textures with the D3D11_RESOURCE_MISC_TEXTURECUBE flag 170 171- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_10_0 172- Cube map arrays require D3D_FEATURE_LEVEL_10_1 173- TODO: are (non)seamless cube maps supported in D3D11? how? 174 175Surfaces 176-------- 177 178Surfaces are views of a resource that can be bound as a framebuffer to serve as the render target or depth buffer. 179 180TODO: write much more on surfaces 181 182OpenGL: FBOs are collections of surfaces in GL 3.0 or GL_ARB_framebuffer_object 183 184D3D11: render target views and depth/stencil views 185 186Sampler views 187------------- 188 189Sampler views are views of a resource that can be bound to a pipeline stage to be sampled from shaders. 190 191TODO: write much more on sampler views 192 193OpenGL: texture objects are actually sampler view and resource in a single unit 194 195D3D11: shader resource views 196