diff options
Diffstat (limited to 'src/gallium/docs/source')
| -rw-r--r-- | src/gallium/docs/source/conf.py | 4 | ||||
| -rw-r--r-- | src/gallium/docs/source/context.rst | 99 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/blend.rst | 2 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/rasterizer.rst | 76 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/velems.rst | 24 | ||||
| -rw-r--r-- | src/gallium/docs/source/screen.rst | 202 |
6 files changed, 255 insertions, 152 deletions
diff --git a/src/gallium/docs/source/conf.py b/src/gallium/docs/source/conf.py index 59c19ed98d..ccc84405c4 100644 --- a/src/gallium/docs/source/conf.py +++ b/src/gallium/docs/source/conf.py @@ -45,9 +45,9 @@ copyright = u'2009, VMWare, X.org, Nouveau' # built documents. # # The short X.Y version. -version = '0.3' +version = '0.4' # The full version, including alpha/beta/rc tags. -release = '0.3' +release = '0.4' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index 9080addba4..c82e681a25 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -24,6 +24,7 @@ CSO objects handled by the context object: * :ref:`Depth, Stencil, & Alpha`: ``*_depth_stencil_alpha_state`` * :ref:`Shader`: These have two sets of methods. ``*_fs_state`` is for fragment shaders, and ``*_vs_state`` is for vertex shaders. +* :ref:`Vertex Elements`: ``*_vertex_elements_state`` Resource Binding State @@ -39,8 +40,7 @@ buffers, surfaces) are bound to the driver. are mostly restricted to the first one right now). * ``set_framebuffer_state`` -* ``set_fragment_sampler_textures`` -* ``set_vertex_sampler_textures`` + * ``set_vertex_buffers`` @@ -50,6 +50,7 @@ Non-CSO State These pieces of state are too small, variable, and/or trivial to have CSO objects. They all follow simple, one-method binding calls, e.g. ``set_blend_color``. + * ``set_stencil_ref`` sets the stencil front and back reference values which are used as comparison values in stencil test. * ``set_blend_color`` @@ -60,7 +61,41 @@ objects. They all follow simple, one-method binding calls, e.g. not have the scissor test enabled, then the scissor bounds never need to be set since they will not be used. * ``set_viewport_state`` -* ``set_vertex_elements`` + + +Sampler Views +^^^^^^^^^^^^^ + +These are the means to bind textures to shader stages. To create one, specify +its format, swizzle and LOD range in sampler view template. + +If texture format is different than template format, it is said the texture +is being cast to another format. Casting can be done only between compatible +formats, that is formats that have matching component order and sizes. + +Swizzle fields specify they way in which fetched texel components are placed +in the result register. For example, ``swizzle_r`` specifies what is going to be +placed in first component of result register. + +The ``first_level`` and ``last_level`` fields of sampler view template specify +the LOD range the texture is going to be constrained to. + +* ``set_fragment_sampler_views`` binds an array of sampler views to + fragment shader stage. Every binding point acquires a reference + to a respective sampler view and releases a reference to the previous + sampler view. + +* ``set_vertex_sampler_views`` binds an array of sampler views to vertex + shader stage. Every binding point acquires a reference to a respective + sampler view and releases a reference to the previous sampler view. + +* ``create_sampler_view`` creates a new sampler view. ``texture`` is associated + with the sampler view which results in sampler view holding a reference + to the texture. Format specified in template must be compatible + with texture format. + +* ``sampler_view_destroy`` destroys a sampler view and releases its reference + to associated texture. Clearing @@ -118,6 +153,12 @@ vertex attributes. If ``indexBuffer`` is NULL, the sequential numbers are used directly as indices to fetch vertex attributes. +``indexBias`` is a value which is added to every index read from the index +buffer before fetching vertex attributes. + +``minIndex`` and ``maxIndex`` describe minimum and maximum index contained in +the index buffer. + If a given vertex element has ``instance_divisor`` set to 0, it is said it contains per-vertex data and effective vertex attribute address needs to be recalculated for every index. @@ -204,9 +245,7 @@ Flushing Resource Busy Queries ^^^^^^^^^^^^^^^^^^^^^ -``is_texture_referenced`` - -``is_buffer_referenced`` +``is_resource_referenced`` @@ -230,3 +269,51 @@ The interfaces to these calls are likely to change to make it easier for a driver to batch multiple blits with the same source and destination. + +Transfers +^^^^^^^^^ + +These methods are used to get data to/from a resource. + +``get_transfer`` creates a transfer object. + +``transfer_destroy`` destroys the transfer object. May cause +data to be written to the resource at this point. + +``transfer_map`` creates a memory mapping for the transfer object. +The returned map points to the start of the mapped range according to +the box region, not the beginning of the resource. + +.. _transfer_flush_region: +``transfer_flush_region`` If a transfer was created with TRANFER_FLUSH_EXPLICIT, +only the region specified is guaranteed to be written to. This is relative to +the mapped range, not the beginning of the resource. + +``transfer_unmap`` remove the memory mapping for the transfer object. +Any pointers into the map should be considered invalid and discarded. + +``transfer_inline_write`` performs a simplified transfer for simple writes. +Basically get_transfer, transfer_map, data write, transfer_unmap, and +transfer_destroy all in one. + +.. _pipe_transfer: + +PIPE_TRANSFER +^^^^^^^^^^^^^ + +These flags control the behavior of a transfer object. + +* ``READ``: resource contents are read at transfer create time. +* ``WRITE``: resource contents will be written back at transfer destroy time. +* ``MAP_DIRECTLY``: a transfer should directly map the resource. May return + NULL if not supported. +* ``DISCARD``: The memory within the mapped region is discarded. + Cannot be used with ``READ``. +* ``DONTBLOCK``: Fail if the resource cannot be mapped immediately. +* ``UNSYNCHRONIZED``: Do not synchronize pending operations on the resource + when mapping. The interaction of any writes to the map and any + operations pending on the resource are undefined. Cannot be used with + ``READ``. +* ``FLUSH_EXPLICIT``: Written ranges will be notified later with + :ref:`transfer_flush_region`. Cannot be used with + ``READ``. diff --git a/src/gallium/docs/source/cso/blend.rst b/src/gallium/docs/source/cso/blend.rst index 55c0f32885..c74396284c 100644 --- a/src/gallium/docs/source/cso/blend.rst +++ b/src/gallium/docs/source/cso/blend.rst @@ -28,7 +28,7 @@ logicop_enable logicop_func The logic operation to use if logic ops are enabled. One of PIPE_LOGICOP. dither - Whether dithering is enabled. + Whether dithering is enabled. Note: Dithering is implementation-dependent. rt Contains the per-rendertarget blend state. diff --git a/src/gallium/docs/source/cso/rasterizer.rst b/src/gallium/docs/source/cso/rasterizer.rst index ccd9136a2e..56a601a8d0 100644 --- a/src/gallium/docs/source/cso/rasterizer.rst +++ b/src/gallium/docs/source/cso/rasterizer.rst @@ -7,7 +7,7 @@ The rasterizer state controls the rendering of points, lines and triangles. Attributes include polygon culling state, line width, line stipple, multisample state, scissoring and flat/smooth shading. -Members +Shading ------- flatshade @@ -46,6 +46,49 @@ There are several important exceptions to the specification of this rule. second vertex, not the first. This permits each segment of the fan to have a different color. +Points +------ + +sprite_coord_enable +^^^^^^^^^^^^^^^^^^^ + +Specifies if a texture unit has its texture coordinates replaced or not. This +is a packed bitfield containing the enable for all texcoords -- if all bits +are zero, point sprites are effectively disabled. If any bit is set, then +point_smooth and point_quad_rasterization are ignored; point smoothing is +disabled and points are always rasterized as quads. If enabled, the four +vertices of the resulting quad will be assigned texture coordinates, +according to sprite_coord_mode. + +sprite_coord_mode +^^^^^^^^^^^^^^^^^ + +Specifies how the value for each shader output should be computed when drawing +point sprites. For PIPE_SPRITE_COORD_LOWER_LEFT, the lower-left vertex will +have coordinates (0,0,0,1). For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left +vertex will have coordinates (0,0,0,1). +This state is used by :ref:`Draw` to generate texcoords. + +.. note:: + + When geometry shaders are available, a special geometry shader could be + used instead of this functionality, to convert incoming points into quads + with the proper texture coordinates. + +point_quad_rasterization +^^^^^^^^^^^^^^^^^^^^^^^^ + +Determines if points should be rasterized as quads or points. Certain APIs, +like Direct3D, always use quad rasterization for points, regardless of +whether point sprites are enabled or not. If this state is enabled, point +smoothing and antialiasing are disabled. If it is disabled, point sprite +coordinates are not generated. + +.. note:: + + Some renderers always internally translate points into quads; this state + still affects those renderers by overriding other rasterization state. + Other Members ^^^^^^^^^^^^^ @@ -107,37 +150,6 @@ point_size_per_vertex Whether vertices have a point size element. point_size The size of points, if not specified per-vertex. -sprite_coord_enable - Specifies if a coord has its texture coordinates replaced or not. This - is a packed bitfield containing the enable for all coords - if all are 0 - point sprites are effectively disabled, though points may still be - rendered slightly different according to point_quad_rasterization. - If any coord is non-zero, point_smooth should be disabled, and - point_quad_rasterization enabled. - If enabled, the four vertices of the resulting quad will be assigned - texture coordinates, according to sprite_coord_mode. -sprite_coord_mode - Specifies how the value for each shader output should be computed when - drawing sprites, for each coord which has sprite_coord_enable set. - For PIPE_SPRITE_COORD_LOWER_LEFT, the lower left vertex will have - coordinate (0,0,0,1). - For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left vertex will have - coordinate (0,0,0,1). - This state is needed by :ref:`Draw` because that's where each - point vertex is converted into four quad vertices. There's no other - place to emit the new vertex texture coordinates which are required for - sprite rendering. - Note that when geometry shaders are available, this state could be - removed. A special geometry shader defined by the state tracker could - convert the incoming points into quads with the proper texture coords. -point_quad_rasterization - This determines if points should be rasterized as quads or points. - d3d always uses quad rasterization for points, regardless if point sprites - are enabled or not, but OGL has different rules. If point_quad_rasterization - is set, point_smooth should be disabled, and points will be rendered as - squares even if multisample is enabled. - sprite_coord_enable should be zero if point_quad_rasterization is not - enabled. scissor Whether the scissor test is enabled. diff --git a/src/gallium/docs/source/cso/velems.rst b/src/gallium/docs/source/cso/velems.rst new file mode 100644 index 0000000000..92cde014fb --- /dev/null +++ b/src/gallium/docs/source/cso/velems.rst @@ -0,0 +1,24 @@ +.. _vertexelements: + +Vertex Elements +=============== + +This state controls format etc. of the input attributes contained +in the pipe_vertex_buffer(s). There's one pipe_vertex_element array member +for each input attribute. + +Members +------- + +src_offset + The byte offset of the attribute in the buffer given by + vertex_buffer_index for the first vertex. +instance_divisor + The instance data rate divisor, used for instancing. + 0 means this is per-vertex data, n means per-instance data used for + n consecutive instances (n > 0). +vertex_buffer_index + The vertex buffer this attribute lives in. Several attributes may + live in the same vertex buffer. +src_format + The format of the attribute data. One of the PIPE_FORMAT tokens. diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst index e78634e59e..c5815f8939 100644 --- a/src/gallium/docs/source/screen.rst +++ b/src/gallium/docs/source/screen.rst @@ -3,16 +3,19 @@ Screen A screen is an object representing the context-independent part of a device. -Useful Flags ------------- +Flags and enumerations +---------------------- + +XXX some of these don't belong in this section. + .. _pipe_cap: -PIPE_CAP -^^^^^^^^ +PIPE_CAP_* +^^^^^^^^^^ -Pipe capabilities help expose hardware functionality not explicitly required -by Gallium. For floating-point values, use :ref:`get_paramf`, and for boolean +Capability queries return information about the features and limits of the +driver/GPU. For floating-point values, use :ref:`get_paramf`, and for boolean or integer values, use :ref:`get_param`. The integer capabilities: @@ -56,6 +59,19 @@ The integer capabilities: to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will only permit binding one constant buffer per shader, and the shaders will not permit two-dimensional access to constants. + +If a value greater than 0 is returned, the driver can have multiple +constant buffers bound to shader stages. The CONST register file can +be accessed with two-dimensional indices, like in the example below. + +DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0 +DCL CONST[3][0] # declare first vector of constbuf 3 +MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0 + +For backwards compatibility, one-dimensional access to CONST register +file is still supported. In that case, the constbuf index is assumed +to be 0. + * ``MAX_CONST_BUFFER_SIZE``: Maximum byte size of a single constant buffer. * ``INDEP_BLEND_ENABLE``: Whether per-rendertarget blend enabling and channel masks are supported. If 0, then the first rendertarget's blend mask is @@ -85,77 +101,56 @@ The floating-point capabilities: * ``GUARD_BAND_LEFT``, ``GUARD_BAND_TOP``, ``GUARD_BAND_RIGHT``, ``GUARD_BAND_BOTTOM``: XXX -XXX Is there a better home for this? vvv - -If 0 is returned, the driver is not aware of multiple constant buffers, -supports binding of only one constant buffer, and does not support -two-dimensional CONST register file access in TGSI shaders. - -If a value greater than 0 is returned, the driver can have multiple -constant buffers bound to shader stages. The CONST register file can -be accessed with two-dimensional indices, like in the example below. -DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0 -DCL CONST[3][0] # declare first vector of constbuf 3 -MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0 -For backwards compatibility, one-dimensional access to CONST register -file is still supported. In that case, the constbuf index is assumed -to be 0. +.. _pipe_bind: + +PIPE_BIND_* +^^^^^^^^^^^ + +These flags indicate how a resource will be used and are specified at resource +creation time. Resources may be used in different roles +during their lifecycle. Bind flags are cumulative and may be combined to create +a resource which can be used for multiple things. +Depending on the pipe driver's memory management and these bind flags, +resources might be created and handled quite differently. + +* ``PIPE_BIND_RENDER_TARGET``: A color buffer or pixel buffer which will be + rendered to. Any surface/resource attached to pipe_framebuffer_state::cbufs + must have this flag set. +* ``PIPE_BIND_DEPTH_STENCIL``: A depth (Z) buffer and/or stencil buffer. Any + depth/stencil surface/resource attached to pipe_framebuffer_state::zsbuf must + have this flag set. +* ``PIPE_BIND_DISPLAY_TARGET``: A surface that can be presented to screen. Arguments to + pipe_screen::flush_front_buffer must have this flag set. +* ``PIPE_BIND_SAMPLER_VIEW``: A texture that may be sampled from in a fragment + or vertex shader. +* ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer. +* ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer. +* ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants. +* ``PIPE_BIND_BLIT_SOURCE``: A blit source, as given to surface_copy. +* ``PIPE_BIND_BLIT_DESTINATION``: A blit destination, as given to surface_copy + and surface_fill. +* ``PIPE_BIND_TRANSFER_WRITE``: A transfer object which will be written to. +* ``PIPE_BIND_TRANSFER_READ``: A transfer object which will be read from. +* ``PIPE_BIND_CUSTOM``: +* ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer. +* ``PIPE_BIND_SHARED``: A sharable buffer that can be given to another + process. + +.. _pipe_usage: + +PIPE_USAGE_* +^^^^^^^^^^^^ -.. _pipe_buffer_usage: +The PIPE_USAGE enums are hints about the expected usage pattern of a resource. -PIPE_BUFFER_USAGE -^^^^^^^^^^^^^^^^^ +* ``PIPE_USAGE_DEFAULT``: Expect many uploads to the resource, intermixed with draws. +* ``PIPE_USAGE_DYNAMIC``: Expect many uploads to the resource, intermixed with draws. +* ``PIPE_USAGE_STATIC``: Same as immutable (?) +* ``PIPE_USAGE_IMMUTABLE``: Resource will not be changed after first upload. +* ``PIPE_USAGE_STREAM``: Upload will be followed by draw, followed by upload, ... -These flags control buffer creation. Buffers may only have one role, so -care should be taken to not allocate a buffer with the wrong usage. - -* ``PIXEL``: This is the flag to use for all textures. -* ``VERTEX``: A vertex buffer. -* ``INDEX``: An element buffer. -* ``CONSTANT``: A buffer of shader constants. - -Buffers are inevitably abstracting the pipe's underlying memory management, -so many of their usage flags can be used to direct the way the buffer is -handled. - -* ``CPU_READ``, ``CPU_WRITE``: Whether the user will map and, in the case of - the latter, write to, the buffer. The convenience flag ``CPU_READ_WRITE`` is - available to signify a read/write buffer. -* ``GPU_READ``, ``GPU_WRITE``: Whether the driver will internally need to - read from or write to the buffer. The latter will only happen if the buffer - is made into a render target. -* ``DISCARD``: When set on a map, the contents of the map will be discarded - beforehand. Cannot be used with ``CPU_READ``. -* ``DONTBLOCK``: When set on a map, the map will fail if the buffer cannot be - mapped immediately. -* ``UNSYNCHRONIZED``: When set on a map, any outstanding operations on the - buffer will be ignored. The interaction of any writes to the map and any - operations pending with the buffer are undefined. Cannot be used with - ``CPU_READ``. -* ``FLUSH_EXPLICIT``: When set on a map, written ranges of the map require - explicit flushes using :ref:`buffer_flush_mapped_range`. Requires - ``CPU_WRITE``. - -.. _pipe_texture_usage: - -PIPE_TEXTURE_USAGE -^^^^^^^^^^^^^^^^^^ - -These flags determine the possible roles a texture may be used for during its -lifetime. Texture usage flags are cumulative and may be combined to create a -texture that can be used as multiple things. - -* ``RENDER_TARGET``: A color buffer or pixel buffer which will be rendered to. -* ``DISPLAY_TARGET``: A sharable buffer that can be given to another process. -* ``PRIMARY``: A front color buffer or scanout buffer. -* ``DEPTH_STENCIL``: A depth (Z) buffer or stencil buffer. Gallium does - not explicitly provide for stencil-only buffers, so any stencil buffer - validated here is implicitly also a depth buffer. -* ``SAMPLER``: A texture that may be sampled from in a fragment or vertex - shader. -* ``DYNAMIC``: A texture that will be mapped frequently. PIPE_TEXTURE_GEOM @@ -174,7 +169,7 @@ For example, a compressed format might only be used for POT textures. Methods ------- -XXX moar; got bored +XXX to-do get_name ^^^^^^^^ @@ -216,66 +211,51 @@ and/or front-buffer rendering. is_format_supported ^^^^^^^^^^^^^^^^^^^ -See if a format can be used in a specific manner. +Determine if a resource in the given format can be used in a specific manner. -**usage** is a bitmask of :ref:`PIPE_TEXTURE_USAGE` flags. +**format** the resource format -Returns TRUE if all usages can be satisfied. - -.. note:: +**target** one of the PIPE_TEXTURE_x flags - ``PIPE_TEXTURE_USAGE_DYNAMIC`` is not a valid usage. +**bindings** is a bitmask of :ref:`PIPE_BIND` flags. -.. _texture_create: +**geom_flags** is a bitmask of PIPE_TEXTURE_GEOM_x flags. -texture_create -^^^^^^^^^^^^^^ - -Given a template of texture setup, create a buffer and texture. +Returns TRUE if all usages can be satisfied. -texture_blanket -^^^^^^^^^^^^^^^ -Like :ref:`texture_create`, but use a supplied buffer instead of creating a -new one. +.. _resource_create: -texture_destroy +resource_create ^^^^^^^^^^^^^^^ -Destroy a texture. The buffer backing the texture is destroyed if it has no -more references. +Create a new resource from a template. +The following fields of the pipe_resource must be specified in the template: -buffer_map -^^^^^^^^^^ +target -Map a buffer into memory. +format -**usage** is a bitmask of :ref:`PIPE_BUFFER_USAGE` flags. +width0 -Returns a pointer to the map, or NULL if the mapping failed. +height0 -buffer_map_range -^^^^^^^^^^^^^^^^ +depth0 -Map a range of a buffer into memory. +last_level -The returned map is always relative to the beginning of the buffer, not the -beginning of the mapped range. +nr_samples -.. _buffer_flush_mapped_range: +usage -buffer_flush_mapped_range -^^^^^^^^^^^^^^^^^^^^^^^^^ +bind -Flush a range of mapped memory into a buffer. +flags -The buffer must have been mapped with ``PIPE_BUFFER_USAGE_FLUSH_EXPLICIT``. -**usage** is a bitmask of :ref:`PIPE_BUFFER_USAGE` flags. -buffer_unmap -^^^^^^^^^^^^ +resource_destroy +^^^^^^^^^^^^^^^^ -Unmap a buffer from memory. +Destroy a resource. A resource is destroyed if it has no more references. -Any pointers into the map should be considered invalid and discarded. |