diff options
author | Mukilan Thiyagarajan <mukilan@igalia.com> | 2023-09-14 15:00:42 +0530 |
---|---|---|
committer | Mukilan Thiyagarajan <mukilan@igalia.com> | 2023-09-14 15:00:42 +0530 |
commit | c385b3c9737c17d59cb02e520c3b68b232cb6497 (patch) | |
tree | ad598ffbbdfbcecd6a4cf458abe2afc702d92c27 /third_party/webrender/swgl/README.md | |
parent | 988e05a68b48c9e744bf49459faf41a1bd9b81d7 (diff) | |
download | servo-revert-webrender.tar.gz servo-revert-webrender.zip |
Revert "Upgrade WebRender to e491e1ae637b2eed1e7195855d88357e5eb3ddf9 (#30323)"revert-webrender
This reverts commit a9d37cb85ac2c55fc630fccffe1ba60ff00f555b.
Diffstat (limited to 'third_party/webrender/swgl/README.md')
-rw-r--r-- | third_party/webrender/swgl/README.md | 220 |
1 files changed, 2 insertions, 218 deletions
diff --git a/third_party/webrender/swgl/README.md b/third_party/webrender/swgl/README.md index 2c43ed88195..158a4157930 100644 --- a/third_party/webrender/swgl/README.md +++ b/third_party/webrender/swgl/README.md @@ -1,220 +1,4 @@ -# swgl +swgl +======== Software OpenGL implementation for WebRender - -## Overview -This is a relatively simple single threaded software rasterizer designed -for use by WebRender. It will shade one quad at a time using a 4xf32 vector -with one vertex per lane. It rasterizes quads usings spans and shades that -span 4 pixels at a time. - -## Building -clang-cl is required to build on Windows. This can be done by installing -the llvm binaries from https://releases.llvm.org/ and adding the installation -to the path with something like `set PATH=%PATH%;C:\Program Files\LLVM\bin`. -Then `set CC=clang-cl` and `set CXX=clang-cl`. That should be sufficient -for `cc-rs` to use `clang-cl` instead of `cl`. - -## Extensions -SWGL contains a number of OpenGL and GLSL extensions designed to both ease -integration with WebRender and to help accelerate span rasterization. - -GLSL extension intrinsics are generally prefixed with `swgl_` to distinguish -them from other items in the GLSL namespace. - -Inside GLSL, the `SWGL` preprocessor token is defined so that usage of SWGL -extensions may be conditionally compiled. - -``` -void swgl_drawSpanRGBA8(); -void swgl_drawSpanR8(); - -int swgl_SpanLength; -int swgl_StepSize; - -mixed swgl_interpStep(mixed varying_input); -void swgl_stepInterp(); -``` - -SWGL's default fragment processing calls a fragment shader's `main` function -on groups of fragments in units of `swgl_StepSize`. On return, the value of -gl_FragColor is read, packed to an appropriate pixel format, and sent to the -blend stage for output to the destination framebuffer. This can be inefficient -for some types of fragment shaders, such as those that must lookup from a -texture and immediately output it, unpacking the texels only to subsequently -repack them at cost. Also, various per-fragment conditions in the shader might -need to be repeatedly checked, even though they are actually constant over -the entire primitive. - -To work around this inefficiency, SWGL allows fragments to optionally be -processed over entire spans. This can both side-step the packing inefficiency -as well as more efficiently deal with conditions that remain constant over an -entire span. SWGL also introduces various specialized intrinsics for more -efficiently dealing with certain types of primitive spans with optimal -fixed-function processing. - -Inside a fragment shader, a `swgl_drawSpan` function may be defined to override -the normal fragment processing for that fragment shader. The function must then -call some form of `swgl_commit` intrinsic to actually output to the destination -framebuffer via the blend stage, as normal fragment processing does not take -place otherwise as would have happened in `main`. This function is used by the -rasterizer to process an entire span of fragments that have passed the depth -test (if applicable) and clipping, but have not yet been output to the blend -stage. - -The amount of fragments within the span to be processed is designated by -`swgl_SpanLength` and is always aligned to units of `swgl_StepSize`. -The size of a group of fragments in terms of which `swgl_commit` intrinsics -process and output fragments is designated by `swgl_StepSize`. The -`swgl_commit` intrinsics will deduct accordingly from `swgl_SpanLength` in -units of `swgl_StepSize` to reflect the fragments actually processed, which -may be less than the entire span or up to the entire span. - -Fragments should be output until `swgl_SpanLength` becomes zero to process the -entire span. If `swgl_drawSpan` returns while leaving any fragments unprocessed, -the remaining fragments will be processed as normal by the fragment shader's -`main` function. This can be used to conditionally handle certain fast-paths -in a fragment shader by otherwise defaulting to the `main` function if -`swgl_drawSpan` can't appropriately process some or all of the fragments. - -The values of any varying inputs to the fragment shader will be set to their -values for the start of the span, but do not automatically update over the -the course of a span within a given call to `swgl_drawSpan`. The -`swgl_interpStep` intrinsic may be used to get the derivative per `swgl_StepSize` -group of fragments of a varying input so that the caller may update such -variables manually if desired or otherwise use that information for processing. -The `swgl_stepInterp` intrinsic forces all such varying inputs to advance by -a single step. - -The RGBA8 version will be used when the destination framebuffer is RGBA8 format, -and the R8 version will be used when the destination framebuffer is R8. Various -other intrinsics described below may have restrictions on whether they can be -used only with a certain destination framebuffer format and are noted as such if -so. - -``` -void swgl_clipMask(sampler2D mask, vec2 offset, vec2 bb_origin, vec2 bb_size); -``` - -When called from the the vertex shader, this specifies a clip mask texture to -be used to mask the currently drawn primitive while blending is enabled. This -mask will only apply to the current primitive. - -The mask must be an R8 texture that will be interpreted as alpha weighting -applied to the source pixel prior to the blend stage. It is sampled 1:1 with -nearest filtering without any applied transform. The given offset specifies -the positioning of the clip mask relative to the framebuffer's viewport. - -The supplied bounding box constrains sampling of the clip mask to only fall -within the given rectangle, specified relative to the clip mask offset. -Anything falling outside this rectangle will be clipped entirely. If the -rectangle is empty, then the clip mask will be ignored. - -``` -void swgl_antiAlias(int edgeMask); -``` - -When called from the vertex shader, this enables anti-aliasing for the -currently drawn primitive while blending is enabled. This setting will only -apply to the current primitive. Anti-aliasing will be applied only to the -edges corresponding to bits supplied in the mask. For simple use-cases, -the edge mask can be set to all 1 bits to enable AA for the entire quad. - -The order of the bits in the edge mask must match the winding order in which -the vertices are output in the vertex shader if processed as a quad, so that -the edge ends on that vertex. The easiest way to understand this ordering -is that for a rectangle (x0,y0,x1,y1) then the edge Nth edge bit corresponds -to the edge where Nth coordinate in the rectangle is constant. - -SWGL tries to use an anti-aliasing method that is reasonably close to WR's -signed-distance field approximation. WR would normally try to discern the -2D local-space coordinates of a given destination pixel relative to the -2D local-space bounding rectangle of a primitive. It then uses the screen- -space derivative to try to determine the how many local-space units equate -to a distance of around one screen-space pixel. A distance approximation -of coverage is then used based on the distance in local-space from the -the current pixel's center, roughly at half-intensity at pixel center -and ranging to zero or full intensity within a radius of half a pixel -away from the center. To account for AAing going outside the normal geometry -boundaries of the primitive, WR has to extrude the primitive by a local-space -estimate to allow some AA to happen within the extruded region. - -SWGL can ultimately do this approximation more simply and get around the -extrusion limitations by just ensuring spans encompass any pixel that is -partially covered when computing span boundaries. Further, since SWGL already -knows the slope of an edge and the coordinate of the span relative to the span -boundaries, finding the partial coverage of a given span becomes easy to do -without requiring any extra interpolants to track against local-space bounds. -Essentially, SWGL just performs anti-aliasing on the actual geometry bounds, -but when the pixels on a span's edge are determined to be partially covered -during span rasterization, it uses the same distance field method as WR on -those span boundary pixels to estimate the coverage based on edge slope. - -``` -void swgl_commitTextureLinearRGBA8(sampler, vec2 uv, vec4 uv_bounds); -void swgl_commitTextureLinearR8(sampler, vec2 uv, vec4 uv_bounds); -void swgl_commitTextureLinearR8ToRGBA8(sampler, vec2 uv, vec4 uv_bounds); - -void swgl_commitTextureLinearColorRGBA8(sampler, vec2 uv, vec4 uv_bounds, vec4|float color); -void swgl_commitTextureLinearColorR8(sampler, vec2 uv, vec4 uv_bounds, vec4|float color); -void swgl_commitTextureLinearColorR8ToRGBA8(sampler, vec2 uv, vec4 uv_bounds, vec4|float color); - -void swgl_commitTextureLinearRepeatRGBA8(sampler, vec2 uv, vec2 tile_repeat, vec4 uv_repeat, vec4 uv_bounds); -void swgl_commitTextureLinearRepeatColorRGBA8(sampler, vec2 uv, vec2 tile_repeat, vec4 uv_repeat, vec4 uv_bounds, vec4|float color); - -void swgl_commitTextureNearestRGBA8(sampler, vec2 uv, vec4 uv_bounds); -void swgl_commitTextureNearestColorRGBA8(sampler, vec2 uv, vec4 uv_bounds, vec4|float color); - -void swgl_commitTextureNearestRepeatRGBA8(sampler, vec2 uv, vec2 tile_repeat, vec4 uv_repeat, vec4 uv_bounds); -void swgl_commitTextureNearestRepeatColorRGBA8(sampler, vec2 uv, vec2 tile_repeat, vec4 uv_repeat, vec4 uv_bounds, vec4|float color); - -void swgl_commitTextureRGBA8(sampler, vec2 uv, vec4 uv_bounds); -void swgl_commitTextureColorRGBA8(sampler, vec2 uv, vec4 uv_bounds, vec4|float color); - -void swgl_commitTextureRepeatRGBA8(sampler, vec2 uv, vec2 tile_repeat, vec4 uv_repeat, vec4 uv_bounds); -void swgl_commitTextureRepeatColorRGBA8(sampler, vec2 uv, vec2 tile_repeat, vec4 uv_repeat, vec4 uv_bounds, vec4|float color); - -void swgl_commitPartialTextureLinearR8(int len, sampler, vec2 uv, vec4 uv_bounds); -void swgl_commitPartialTextureLinearInvertR8(int len, sampler, vec2 uv, vec4 uv_bounds); -``` - -Samples and commits an entire span of texture starting at the given uv and -within the supplied uv bounds. The color variations also accept a supplied color -that modulates the result. - -The RGBA8 versions may only be used to commit within `swgl_drawSpanRGBA8`, and -the R8 versions may only be used to commit within `swgl_drawSpanR8`. The R8ToRGBA8 -versions may be used to sample from an R8 source while committing to an RGBA8 -framebuffer. - -The Linear variations use a linear filter that bilinearly interpolates between -the four samples near the pixel. The Nearest variations use a nearest filter -that chooses the closest aliased sample to the center of the pixel. If neither -Linear nor Nearest is specified in the `swgl_commitTexture` variation name, then -it will automatically select either the Linear or Nearest variation depending -on the sampler's specified filter. - -The Repeat variations require an optional repeat rect that specifies how to -scale and offset the UVs, assuming the UVs are normalized to repeat in the -range 0 to 1. For NearestRepeat variations, it is assumed the repeat rect is -always within the bounds. The tile repeat limit, if non-zero, specifies the -maximum number of repetitions allowed. - -The Partial variations allow committing only a sub-span rather the entire -remaining span. These are currently only implemented in linear R8 variants -for optimizing clip shaders in WebRender. The Invert variant of these is -useful for implementing clip-out modes by inverting the source texture value. - -``` -// Premultiplied alpha over blend, but with source color set to source alpha modulated with a constant color. -void swgl_blendDropShadow(vec4 color); -// Premultiplied alpha over blend, but treats the source as a subpixel mask modulated with a constant color. -void swgl_blendSubpixelText(vec4 color); -``` - -SWGL allows overriding the blend mode per-primitive by calling `swgl_blend` -intrinsics in the vertex shader. The existing blend mode set by the GL is -replaced with the one specified by the intrinsic for the current primitive. -The blend mode will be reset to the blend mode set by the GL for the next -primitive after the current one, even within the same draw call. - |