Home | History | Annotate | Download | only in source 
      1 Resources and derived objects
      2 =============================
      3 
      4 Resources represent objects that hold data: textures and buffers.
      5 
      6 They are mostly modelled after the resources in Direct3D 10/11, but with a
      7 different transfer/update mechanism, and more features for OpenGL support.
      8 
      9 Resources can be used in several ways, and it is required to specify all planned uses through an appropriate set of bind flags.
     10 
     11 TODO: write much more on resources
     12 
     13 Transfers
     14 ---------
     15 
     16 Transfers are the mechanism used to access resources with the CPU.
     17 
     18 OpenGL: OpenGL supports mapping buffers and has inline transfer functions for both buffers and textures
     19 
     20 D3D11: D3D11 lacks transfers, but has special resource types that are mappable to the CPU address space
     21 
     22 TODO: write much more on transfers
     23 
     24 Resource targets
     25 ----------------
     26 
     27 Resource targets determine the type of a resource.
     28 
     29 Note that drivers may not actually have the restrictions listed regarding
     30 coordinate normalization and wrap modes, and in fact efficient OpenCL
     31 support will probably require drivers that don't have any of them, which
     32 will probably be advertised with an appropriate cap.
     33 
     34 TODO: document all targets. Note that both 3D and cube have restrictions
     35 that depend on the hardware generation.
     36 
     37 TODO: can buffers have a non-R8 format?
     38 
     39 PIPE_BUFFER
     40 ^^^^^^^^^^^
     41 
     42 Buffer resource: can be used as a vertex, index, constant buffer (appropriate bind flags must be requested).
     43 
     44 They can be bound to stream output if supported.
     45 TODO: what about the restrictions lifted by the several later GL transform feedback extensions? How does one advertise that in Gallium?
     46 
     47 They can be also be bound to a shader stage as usual.
     48 TODO: are all drivers supposed to support this? how does this work exactly? are there size limits?
     49 
     50 They can be also be bound to the framebuffer as usual.
     51 TODO: are all drivers supposed to support this? how does this work exactly? are there size limits?
     52 TODO: 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 
     60 OpenGL: 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 
     67 D3D11: buffer resources
     68 - Binding to a render target requires D3D_FEATURE_LEVEL_10_0
     69 
     70 PIPE_TEXTURE_1D
     71 ^^^^^^^^^^^^^^^
     72 1D surface accessed with normalized coordinates.
     73 
     74 UNIMPLEMENTED: 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 
     83 OpenGL: 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 
     87 D3D11: 1D textures in D3D_FEATURE_LEVEL_10_0
     88 
     89 PIPE_TEXTURE_RECT
     90 ^^^^^^^^^^^^^^^^^
     91 2D 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 
     98 OpenGL: GL_TEXTURE_RECTANGLE in GL 3.1 or GL_ARB_texture_rectangle or GL_NV_texture_rectangle
     99 
    100 OpenCL: can create OpenCL images based on this, that can then be sampled arbitrarily
    101 
    102 D3D11: not supported (only PIPE_TEXTURE_2D with normalized coordinates is supported)
    103 
    104 PIPE_TEXTURE_2D
    105 ^^^^^^^^^^^^^^^
    106 2D surface accessed with normalized coordinates.
    107 
    108 UNIMPLEMENTED: 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 
    117 OpenGL: 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 
    121 OpenCL: can create OpenCL images based on this, that can then be sampled arbitrarily
    122 
    123 D3D11: 2D textures
    124 
    125 - PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_9_3
    126 
    127 PIPE_TEXTURE_3D
    128 ^^^^^^^^^^^^^^^
    129 
    130 3-dimensional array of texels.
    131 Mipmap 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 
    137 OpenGL: 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 
    141 D3D11: 3D textures
    142 
    143 - PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_10_0
    144 
    145 PIPE_TEXTURE_CUBE
    146 ^^^^^^^^^^^^^^^^^
    147 
    148 Cube maps consist of 6 2D faces.
    149 The 6 surfaces form an imaginary cube, and sampling happens by mapping an
    150 input 3-vector to the point of the cube surface in that direction.
    151 
    152 Sampling may be optionally seamless, resulting in filtering taking samples
    153 from multiple surfaces near to the edge.
    154 UNIMPLEMENTED: seamless cube map sampling not supported
    155 
    156 UNIMPLEMENTED: 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 
    163 OpenGL: 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 
    169 D3D11: 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 
    175 Surfaces
    176 --------
    177 
    178 Surfaces are views of a resource that can be bound as a framebuffer to serve as the render target or depth buffer.
    179 
    180 TODO: write much more on surfaces
    181 
    182 OpenGL: FBOs are collections of surfaces in GL 3.0 or GL_ARB_framebuffer_object
    183 
    184 D3D11: render target views and depth/stencil views
    185 
    186 Sampler views
    187 -------------
    188 
    189 Sampler views are views of a resource that can be bound to a pipeline stage to be sampled from shaders.
    190 
    191 TODO: write much more on sampler views
    192 
    193 OpenGL: texture objects are actually sampler view and resource in a single unit
    194 
    195 D3D11: shader resource views
    196