This diagram shows the rendering pipeline with an emphasis on
the inputs/outputs for each stage. Some stages emit new vertex
attributes and others consume some attributes.
I'm not sure if I really got it right. This seems like one of those
"Duh, of course it works that way" things, but I'd like the
documentation to be readable by people not acquainted with OGL/D3D.
clears were a bit limited in gallium:
- no scissoring (OGL only) nor explicit rectangle list (d3d9)
- no color/stencil masks (OGL only)
- no separate depth/stencil clears (d3d9/d3d10/OGL)
- cannot really clear single color buffer (only with resource_fill_region)
Additionally, d3d can clear surfaces not currently bound to the framebuffer.
It is, however, not easy to find some common ground what a clear should be able
to do, due to both API requirements and also hw differences (a case which might
be able to use a special clear path on one hw might need a "normal" quad render
on another).
Hence several clear methods are provided, and a driver should implement all of
them.
- clear: slightly modified to also be able to clear only depth or stencil in a
combined depth/stencil surface. This is however optional based on driver
capability though ideally it wouldn't be optional. AFAIK this is in fact
something used by applications quite a bit.
Otherwise, for now still doesn't allow clearing with scissors/mask (or single
color buffers)
- clearRT: clears a single (potentially unbound) color surface. This was formerly
roughly known as resource_fill_region. mesa st will not currently use this,
though potentially would be useful for GL ClearBuffer.
- clearDS: similar to above except for depth stencil surfaces.
Note that clearDS/clearRT currently handle can handle partial clear. This might
change however.
Previously, surface_copy was said to allow overlapping blits, and it was
"optional". However, some state trackers actually assumed it is always present,
and quite some code (like in u_blit) assumed overlapping isn't allowed.
Hence, resource_copy_region (and in the same spirit, resource_fill_region) is
now mandatory, but overlapping blits are no longer allowed. A driver can plug
in the cpu fallback util_resource_copy_region if it does not want to provide its
own implementation, though this is not optimal.
due to popular request, use nr_samples parameter in is_format_supported()
instead of new is_msaa_supported() query.
This makes it easily possible to query if a format with a given sample count
is also supported not only as render target, but for sampler views (note that
texture sampling from multisampled resources isn't supported yet).
It is not quite how dx10 format msaa queries work, but we might need to revisit
format queries completely in the future anyway.
add function to set sample mask, and state for alpha-to-coverage and
alpha-to-one. Also make it possible to query for supported sample count
with is_msaa_supported().
Use explicit resource_resolve() to resolve a resource. Note that it is illegal
to bind a unresolved resource as a sampler view, must be resolved first (as per
d3d10 and OGL APIs, binding unresolved resource would mean that special texture
fetch functions need to be used which give explicit control over what samples
to fetch, which isn't supported yet).
Also change surface_fill() and surface_copy() to operate directly on resources.
Blits should operate directly on resources, most often state trackers just used
get_tex_surface() then did a blit. Note this also means the blit bind flags are
gone, if a driver implements this functionality it is expected to handle it for
all resources having depth_stencil/render_target/sampler_view bind flags (might
even require it for all bind flags?).
Might want to introduce quality levels for MSAA later.
Might need to revisit this for hw which does instant resolve.
