Skip to content

A
angle
Commit 3c7fee36 by Andrew Bonventre Committed by Geoff Lang
Options

[Docs] Add wiki content to Markdown docs

Change-Id: I729d3208b206e83f99e73002b45402c4f6f9f443 Reviewed-on: https://chromium-review.googlesource.com/301560Reviewed-by: 's avatarGeoff Lang <geofflang@chromium.org> Reviewed-by: 's avatarCorentin Wallez <cwallez@chromium.org> Tested-by: 's avatarGeoff Lang <geofflang@chromium.org>
parent 3aa23a7c
Showing with 950 additions and 22 deletions
doc/64BitSafety.md 0 → 100644
# 64-bit Safety In the Compiler
An issue that has arisen recently for contributors making changes to the GLSL ES
grammar files has been that certain versions of flex, the lexer on which ANGLE
relies, produce outputs which are not safe in 64-bit builds.
To address this issue, ANGLE has added a step to its generation scripts to apply
64-bit safety fixes to newly regenerated outputs. This should be unnoticeable to
developers invoking flex via the generate\_parser.sh scripts in the relevant
compiler directories, as the fixes will be applied by the patch utility as part
of that script.
When making code contributions that affect the grammar files, please ensure that
you've generated the outputs using the script, to make certain that the 64-bit
safety fixes are applied.
doc/BranchingAndRolling.md 0 → 100644
# How to Branch and Roll Chromium's ANGLE Dependency
ANGLE provides an implementation of OpenGL ES on Windows, which Chromium relies
upon for hardware accelerated rendering and WebGL support. Chromium specifies
its dependency on a specific version of ANGLE in the repository; this document
describes how to update that dependency, and, if necessary, create an ANGLE
branch to correspond to a branched release of Chrome.
## Rolling DEPS
Chromium's dependency on third-party projects is tracked in [the Chromium
repository's src/DEPS file]
(http://src.chromium.org/viewvc/chrome/trunk/src/DEPS). To update the ANGLE
dependency: * Find the line in this file that defines "src/third\_party/angle"
for deps (**not** deps\_os) * Change the [git SHA-1 revision number]
(http://git-scm.com/book/ch6-1.html) to be that of the commit on which Chromium
should depend. Please use the full SHA-1, not a shortened version. * You can
find the SHA-1 for a particular commit with `git log` on the appropriate branch
of the repository, or via [the public repository viewer]
(https://chromium.googlesource.com/angle/angle). * If using the public
repository viewer, you will need to select the branch whose log you wish to view
from the list on the left-hand side, and then click on the "tree" link at the
top of the resulting page. Alternatively, you can navigate to
`https://chromium.googlesource.com/angle/angle/+/<branch name>/` -- including
the terminating forward slash. (e.g.
`https://chromium.googlesource.com/angle/angle/+/master/`)
## Branching ANGLE
Sometimes, individual changes to ANGLE are needed for a release of Chrome which
has already been branched. If this is the case, a branch of ANGLE should be
created to correspond to the Chrome release version, so that Chrome may
incorporate only these changes, and not everything that has been committed since
the version on which Chrome depended at branch time. **Please note: Only ANGLE
admins can create a new branch.** To create a branch of ANGLE for a branched
Chrome release: * Determine what the ANGLE dependency is for the Chrome release
by checking the DEPS file for that branch. * Check out this commit as a new
branch in your local repository. * e.g., for [the Chrome 34 release at
chrome/branches/1847]
(http://src.chromium.org/viewvc/chrome/branches/1847/src/DEPS), the ANGLE
version is 4df02c1ed5e97dd54576b06964b1da67ea30238e. To check this commit out
locally and create a new branch named 'mybranch' from this commit, use: `git
checkout -b mybranch 4df02c1ed5e97dd54576b06964b1da67ea30238e
` * To create this new branch in the public repository, you'll need to push the
branch to the special Gerrit reference location, 'refs/heads/<branch name>'. You
must be an ANGLE administrator to be able to push this new branch. * e.g., to
use your local 'mybranch' to create a branch in the public repository called
'chrome\_m34', use: `git push origin mybranch:refs/heads/chrome_m34
` * The naming convention that ANGLE uses for its release-dedicated branches is
'chrome\_m##'.
doc/BufferImplementation.md 0 → 100644
# Introduction
Since Direct3D 9 only supports buffers that either contain vertex or index data,
and OpenGL buffers can contain both, ANGLE waits till a draw call is issued to
determine which resources to create/update. The generic implementation 'streams'
the data into global vertex and index buffers. This streaming buffer
implementation works in all circumstances, but does not offer optimal
performance. When buffer data isn't updated, there's no reason to copy the data
again. For these cases a 'static' buffer implementation is used.
The OpenGL ES 2.0 glBufferData() function allows to specify a usage hint
parameter (GL\_STREAM\_DRAW, GL\_DYNAMIC\_DRAW or GL\_STATIC\_DRAW). Both
GL\_STREAM\_DRAW and GL\_DYNAMIC\_DRAW use the streaming buffer implementation.
With the GL\_STATIC\_DRAW hint, ANGLE will attempt to use the static buffer
implementation. If you update the buffer data after it has already been used in
a draw call, it falls back to the streaming buffer implementation, because
updating static ones would involve creating new ones, which is slower than
updating streaming ones (more on this later).
Because some applications use GL\_STREAM\_DRAW or GL\_DYNAMIC\_DRAW even when
the data is not or very infrequently updated, ANGLE also has a heuristic to
promote buffers to use the static implementation.
# Streaming buffers
The streaming buffers implementation uses one Context-global vertex buffer
(VertexDataManager::mStreamingBuffer) and two index buffers
(IndexDataManager::mStreamingBufferShort and
IndexDataManager::mStreamingBufferInt). The streaming behavior is achieved by
writing new data behind previously written data (i.e. without overwriting old
data). Direct3D 9 allows to efficiently update vertex and index buffers when
you're not reading or overwriting anything (it won't stall waiting for the GPU
finish using it).
When the end of these streaming buffers is reached, they are 'recycled' by
discarding their content. D3D9 will still keep a copy of the data that's in use,
so this recycling efficiently renames the driver level buffers. ANGLE can then
write new data to the beginning of the vertex or index buffer.
The ArrayVertexBuffer::mWritePosition variable holds the current end position of
the last data that was written. StreamingVertexBuffer::reserveRequiredSpace()
allocates space to write the data, and StreamingVertexBuffer::map() actually
locks the D3D buffer and updates the write position. Similar for index buffers.
# Static buffers
Each GL buffer object can have a corresponding static vertex or index buffer
(Buffer::mVertexBuffer and Buffer::mIndexBuffer). When a GL buffer with static
usage is used in a draw call for the first time, all of its data is converted to
a D3D vertex or index buffer, based on the attribute or index formats
respectively. If a subsequent draw call uses different formats, the static
buffer is invalidated (deleted) and the streaming buffer implementation is used
for this buffer object instead. So for optimal performance it's important to
store only a single format of vertices or indices in a buffer. This is highly
typical, and even when in some cases it falls back to the streaming buffer
implementation the performance isn't bad at all.
The StreamingVertexBuffer and StaticVertexBuffer classes share a common base
class, ArrayVertexBuffer. StaticVertexBuffer also has access to the write
position, but it's used only for the initial conversion of the data. So the
interfaces of both classes are not that different. Static buffers have an exact
size though, and can't be changed afterwards (streaming buffers can grow to
handle draw calls which use more data, and avoid excessive recycling).
StaticVertexBuffer has a lookupAttribute() method to retrieve the location of a
certain attribute (this is also used to verify that the formats haven't changed,
which would result in invalidating the static buffer). The descriptions of all
the attribute formats a static buffer contains are stored in the
StaticVertexBuffer::mCache vector.
StaticIndexBuffer also caches information about what's stored in them, namely
the minimum and maximum value for certain ranges of indices. This information is
required by the Direct3D 9 draw calls, and is also used to know the range of
vertices that need to be copied to the streaming vertex buffer in case it needs
to be used (e.g. it is not uncommon to have a buffer with static vertex position
data and a buffer with streaming texture coordinate data for skinning).
# Constant attributes
Aside from using array buffers to feed attribute data to the vertex shader,
OpenGL also supports attributes which remain constant for all vertices used in a
draw call. Direct3D 9 doesn't have a similar concept, at least not explicitly.
Constant attributes are implementated using separate (static) vertex buffers,
and uses a stride of 0 to ensure that every vertex retrieves the same data.
Using a stride of 0 is not possible with streaming buffers because on some
hardware it is incompatible with the D3DUSAGE\_DYNAMIC flag. We found that with
static usage, all hardware tested so far can handle stride 0 fine.
This functionality was implemented in a ConstantVertexBuffer class, and it
integrates nicely with the rest of the static buffer implementation.
# Line loops
Direct3D 9 does not support the 'line loop' primitive type directly. This is
implemented by drawing the 'closing' line segment separately, constructing a
tiny temporary index buffer connecting the last and first vertex.
# Putting it all together
glDrawElements() calls IndexDataManager::prepareIndexData() to retrieve a
Direct3D index buffer containing the necessary data. If an element array is used
(i.e. a buffer object), it has static usage, and it hasn't been invalidated, the
GL buffer's static D3D index buffer will be returned. Else the updated streaming
index buffer is returned, as well as the index offset (write position) where the
new data is located. When prepareIndexData() does find a static index buffer,
but it's empty, it means the GL buffer's data hasn't been converted and stored
in the D3D index buffer yet. So in the convertIndices() call it will convert the
entire buffer. prepareIndexData() will also look up the min/max value of a range
of indices, or computes it when not already in the static buffer or when a
streaming buffer is used.
Similarly, both glDrawElements() and glDrawArrays() both call
VertexDataManager::prepareVertexData() to retrieve a set of Direct3D vertex
buffers and their translated format and offset information. It's implementation
is more complicated than prepareIndexData() because buffer objects can contain
multiple vertex attributes, and multiple buffers can be used as input to the
vertex shader. So first it accumulates how much storage space is required for
each of the buffers in use. For all static non-empty buffers in use, it
determines whether the stored attributes still match what is required by the
draw call, and invalidates them if not (at which point more space is allocated
in the streaming buffer). Converting the GL buffer object's data into D3D
compatible vertex formats is still done by specialized template functions.
doc/ChoosingANGLEBranch.md 0 → 100644
# Choosing an ANGLE branch for your project
ANGLE is under continuous development, and does not create release tarballs or
tag specific revisions as releases, which may make the process of choosing a
point in ANGLE's history as the dependency for your project less than obvious.
This document illustrates how to choose a branch of ANGLE which can be expected
to be updated with critical fixes, should they be needed.
## ANGLE automatic branching
Branches are created automatically in ANGLE to correspond to branches created in
Chromium. These branches are named `chromium/####`, where the number is the
matching Chromium branch. These branches will be created from the revision which
that Chromium branch points to as its dependency. So, for example, the
`chromium/2013` branch point is at r28bcf4ff, because [Chromium's dependency
file for the 2013 branch]
(http://src.chromium.org/viewvc/chrome/branches/2013/src/DEPS?revision=272741)
uses this ANGLE revision.
It isn't necessary to be familiar with how Chromium's dependency management
works to choose an appropriate ANGLE branch for your project. You will, however,
likely want to make sure that you choose a branch that is used for a relatively
stable Chromium release channel build, as those branches will be deployed with
Chromium, and receive updates if bugs are found and fixed during release
lifetime, while the more volatile channels will turn over quickly, and their
branches will be short-lived.
**We recommend choosing a branch corresponding to a Beta or Stable Chromium
release** if you are pursuing periodic, not continuous, integration of ANGLE.
## Matching a Chromium release to an ANGLE branch
In order to determine which branches are used by Chromium releases, please use
[the OmahaProxy tool](http://omahaproxy.appspot.com/), which lists build
information about current Chromium releases. Find the entry for a suitable
release channel (for now, we recommend one of the Windows desktop releases), and
note the branch listed in the `true_branch` column. This identifies the ANGLE
branch used by that Chromium release.
## Updates to release branches
If bugs (stability, security, performance, or otherwise) are discovered after a
branch has been created, and that branch is used by a Chromium release, the
fixes for those bugs will be applied to the ANGLE branches for uptake by
Chromium and any other projects using that branch. You should need only to
perform a `git pull` to check for and apply any such changes.
doc/CodeReviewProcess.md
# ANGLE's Code Review Process # ANGLE's Code Review Process
This page describes the review process for ANGLE reviewers and committers. For instructions on submitting your change list for review, please see [ContributingCode](ContributingCode.md). This page describes the review process for ANGLE reviewers and committers. For
instructions on submitting your change list for review, please see
[ContributingCode](ContributingCode.md).
## Reviewing Changes ## Reviewing Changes
The author of a CL may designate reviewers. Please feel free to weigh in on changes even if you are not a designated reviewer! The author of a CL may designate reviewers. Please feel free to weigh in on
changes even if you are not a designated reviewer!
1. To review a change, you can either navigate directly to the URL for the CL, or, if you are one of the designated reviewers, the change will appear in your dashboard at [https://chromium-review.googlesource.com/](https://chromium-review.googlesource.com/). 1. To review a change, you can either navigate directly to the URL for the CL,
2. Review the change listed by looking over the diffs listed in the most recent patch set. or, if you are one of the designated reviewers, the change will appear in
* You may view the diffs either side-to-side, or in unified diff format. your dashboard at https://chromium-review.googlesource.com/
* You can comment on a specific line of code by double-clicking that line, or on the file as a whole by clicking the "Add file comment" icon, which appears above the diff, in the line number column. 2. Review the change listed by looking over the diffs listed in the most recent
* Note that, for CLs submitted as fixes to standing bugs, style issues that pre-exist the CL are not required to be addressed in the CL. As a reviewer, you can request a follow-up CL to address the style issue if you desire. This exception doesn't apply for CLs which implement new functionality, perform refactoring, or introduce style issues themselves. patch set.
3. Once your review is complete, click the "Review" button * You may view the diffs either side-to-side, or in unified diff format.
* If you are satisfied with the change list as it is, give a positive review (Code-Review +1 or +2). * You can comment on a specific line of code by double-clicking that line,
* If you think the change list is a good idea, but needs changes, leave comments and a neutral review. (Code-Review 0) or on the file as a whole by clicking the "Add file comment" icon, which
* If you think the change list should be abandoned, give a negative review. (Code-Review -1 or -2) appears above the diff, in the line number column.
* A +2 code review is required before landing. Only ANGLE committers may provide a +2 code review. * Note that, for CLs submitted as fixes to standing bugs, style issues
* ANGLE has a 2-reviewer policy for CLs. This means all changes should get a positive review from more than one person before they are accepted. This is most usually handled by reserving the +2 review for the second reviewer to clear the CL. that pre-exist the CL are not required to be addressed in the CL. As a
* If you made comments on the files, the draft comments will appear below the cover message. These comments are not published until you click on the "Publish Comments" button. reviewer, you can request a follow-up CL to address the style issue if
4. Verification and landing: you desire. This exception doesn't apply for CLs which implement new
* If the CL author is not an ANGLE committer, the CL should be verified and landed by a committer. Once verified, the "+1 Verified" status may be added, and the CL may be landed with the "Publish and Submit" button. There should be no need to rebase via the "Rebase Change" button prior to landing. functionality, perform refactoring, or introduce style issues
* If the CL author is an ANGLE committer, they should verify and land the CL themselves. themselves.
* Please note: Verification and commit-queue workflow may be subject to change in the near future. 3. Once your review is complete, click the "Review" button
5. Cherry-picking to other branches * If you are satisfied with the change list as it is, give a positive
* If the change is needed on other branches, you may be able to land it using the "Cherry Pick To" button on the CL page. review (Code-Review +1 or +2).
* If this cherry pick fails, you will need to rebase the patch yourself and submit a new change for review on the branch. * If you think the change list is a good idea, but needs changes, leave
\ No newline at end of file comments and a neutral review. (Code-Review 0)
* If you think the change list should be abandoned, give a negative
review. (Code-Review -1 or -2)
* A +2 code review is required before landing. Only ANGLE committers may
provide a +2 code review.
* ANGLE has a 2-reviewer policy for CLs. This means all changes should get
a positive review from more than one person before they are accepted.
This is most usually handled by reserving the +2 review for the second
reviewer to clear the CL.
* If you made comments on the files, the draft comments will appear below
the cover message. These comments are not published until you click on
the "Publish Comments" button.
4. Verification and landing:
* If the CL author is not an ANGLE committer, the CL should be verified
and landed by a committer. Once verified, the "+1 Verified" status may
be added, and the CL may be landed with the "Publish and Submit" button.
There should be no need to rebase via the "Rebase Change" button prior
to landing.
* If the CL author is an ANGLE committer, they should verify and land the
CL themselves.
* Please note: Verification and commit-queue workflow may be subject to
change in the near future.
5. Cherry-picking to other branches
* If the change is needed on other branches, you may be able to land it
using the "Cherry Pick To" button on the CL page.
* If this cherry pick fails, you will need to rebase the patch yourself
and submit a new change for review on the branch.
doc/CodingStandard.md 0 → 100644
# Coding Standard for the ANGLE Project
## Google Style Guide
We generally use the [Google C++ Style Guide]
(http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) as a basis for
our Coding Standard, however we will deviate from it in a few areas, as noted
below.
Items marked {DEV} indicate a deviation from the Google guidelines. Items marked
{DO} are reiterating points from the Google guidelines.
### [Header Files](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Header_Files)
* We will use **`.h`** for C++ headers.
* {DEV} #define guards should be of the form: `<PATH>_<FILE>_H_`. (Compiler
codebase is varied, including `<PROJECT>_` makes the names excessively
long).
### [Scoping](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Scoping)
* {DO} avoid globally scoped variables, unless absolutely necessary.
### [Classes](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Classes)
* {DO} disable Copy and Assignment constructors using the
DISALLOW\_COPY\_AND\_ASSIGN macro (defined in common/angleutils.h) in the
**private** section of a class: ``` class Foo { public: Foo(int f); ~Foo();
private: DISALLOW_COPY_AND_ASSIGN(Foo); }; ```
### [Other C++ Features](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Other_C++_Features)
* {DEV} all parameters passed by reference, except for STL containers (e.g.
std::vector, std::list), must be labeled `const`. For return parameters
other than STL containers, use a pointer.
* {DO} avoid use of default arguments. exception: for functions emulating
variadic arguments, they are allowed.
* {DONT} use C++ exceptions, they are disabled in the builds and not caught.
* {DO} use nullptr (instead of 0 or NULL) for pointers.
* {DO} use size\_t for loop iterators and size values.
* {DO} use uint8\_t pointers instead of void pointers to denote binary data.
* {DO} use C++11 according to the [Chromium guide on C++11]
(http://chromium-cpp.appspot.com/).
* {DEV} we permit C++11 STL classes inside the D3D Renderers, since D3D is
only supported on MSVS.
### [Naming ](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Naming)
#### File Names
* {DEV} Filenames should be all lowercase and can include underscores (`_`).
If the file is an implementation of a class, the filename may be capitalized
the same as the major class.
* {DEV} We use .cpp (instead of .cc), .h and .inl (inlined files) for C++
files and headers. #### Directory Names
* Directory names should be all lowercase, unless following an externally
imposed capitalization (eg include/EGL, or src/libGLESv2, etc)
#### Variable Names
Use the following guidelines, they do deviate somewhat from the Google
guidelines. * class and type names: start with capital letter and use CamelCase.
* {DEV} class member variables: use an **`m`** prefix instead of trailing
underscore and use CamelCase. * global variables (if they must be used): use a
**`g_`** prefix. * {DEV} variable names: start with lower case and use CamelCase
(chosen for consitency) * {DEV} function names: Member functions start with
lower case and use CamelCase. Non-member functions start with capital letter and
use CamelCase (chosen for consistency) * Constants: start with a **`k`** and use
CamelCase * namespaces: use all lower case * Enumerator Names - follow constants
* macros: all uppercase with underscores * exceptions to naming: use common
sense!
### [Comments](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Comments)
* {DO} read and follow Google's recommendations.
* Each file **must** start with the following boilerplate notice: `// //
Copyright (c) 2002-2011 The ANGLE Project Authors. All rights reserved. //
Use of this source code is governed by a BSD-style license that can be //
found in the LICENSE file. //
`
### [Formatting](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Formatting)
* {DEV} Avoid excessively long lines. Please keep lines under 120 columns
long.
* Use unix-style newlines.
* {DO} use only spaces. No tab characters. Configure your editor to emit
spaces when you hit the TAB-key.
* {DEV} indent 4 spaces at a time.
* conditionals: place space outside the parenthesis. No spaces inside.
* switch statements: indent the case statements by 2 spaces. The body of the
case statements should be intended another 2 spaces so that they are a full
4-space indent from the switch.
* class format(eg private, public, protected): indent by 2 spaces. Regular
4-space indent from the outer scope for declarations/definitions.
* pointers and references: **`*`** and **`&`** tight against the variable
* namespaces: are not indented.
* extern code blocks: are not indented.
* {DEV} braces should go on a separate line, except for functions defined in a
header file where the whole function declaration and definition fit on one
line.
Examples: `if (conditional) { stuff(); } else { otherstuff() }
` `switch (conditional) { case foo: dostuff(); break; case bar: otherstuff()
break; default: WTFBBQ(); }
` `class MyClass : public Foo { public: MyClass(); ~MyClass() {}; private:
DISALLOW_COPY_AND_ASSIGN(MyClass); };
` `char *c; const string &str;
`
### [Exceptions to the Rules](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Exceptions_to_the_Rules)
* If modifying pre-existing code that does not match the standard, the altered
portions of the code should be changed to match the standard.
* For changes which fix bugs, we do not require that pre-existing style issues
be addressed in the change itself, but reviewers may request a follow-on CL
to address style inconsistencies. This exception does not apply to changes
which implement new features, perform refactoring, or introduce a style
issue or inconsistency themselves.
doc/CompilingTranslatorWithEmscripten.md 0 → 100644
# Introduction
There are many situations in which it's useful for WebGL applications to
transform shaders in various ways. ANGLE's shader translator can be used for
this purpose: compiling it with [Emscripten](http://emscripten.org/) allows it
to be invoked from a web page. This wiki page provides some preliminary details
about how to do this.
# Details
Pull top of tree ANGLE.
Install the Emscripten toolchain per the [instructions]
(http://kripken.github.io/emscripten-site/).
Symlink (preferred) or copy the ANGLE directory into ...emsdk/emscripten/master.
Put a shader to compile into a file (named with .vert or .frag suffix) in the
same directory. For example, put the following shader from the [WebGL Aquarium]
(http://webglsamples.org/aquarium/aquarium.html) into `aq-fish-nm.frag`:
```
precision mediump float;
uniform vec4 lightColor;
varying vec4 v_position;
varying vec2 v_texCoord;
varying vec3 v_tangent; // #normalMap
varying vec3 v_binormal; // #normalMap
varying vec3 v_normal;
varying vec3 v_surfaceToLight;
varying vec3 v_surfaceToView;
uniform vec4 ambient;
uniform sampler2D diffuse;
uniform vec4 specular;
uniform sampler2D normalMap; // #normalMap
uniform float shininess;
uniform float specularFactor;
// #fogUniforms
vec4 lit(float l ,float h, float m) {
return vec4(1.0,
max(l, 0.0),
(l > 0.0) ? pow(max(0.0, h), m) : 0.0,
1.0);
}
void main() {
vec4 diffuseColor = texture2D(diffuse, v_texCoord);
mat3 tangentToWorld = mat3(v_tangent, // #normalMap
v_binormal, // #normalMap
v_normal); // #normalMap
vec4 normalSpec = texture2D(normalMap, v_texCoord.xy); // #normalMap
vec3 tangentNormal = normalSpec.xyz - vec3(0.5, 0.5, 0.5); // #normalMap
tangentNormal = normalize(tangentNormal + vec3(0, 0, 2)); // #normalMap
vec3 normal = (tangentToWorld * tangentNormal); // #normalMap
normal = normalize(normal); // #normalMap
vec3 surfaceToLight = normalize(v_surfaceToLight);
vec3 surfaceToView = normalize(v_surfaceToView);
vec3 halfVector = normalize(surfaceToLight + surfaceToView);
vec4 litR = lit(dot(normal, surfaceToLight),
dot(normal, halfVector), shininess);
vec4 outColor = vec4(
(lightColor * (diffuseColor * litR.y + diffuseColor * ambient +
specular * litR.z * specularFactor * normalSpec.a)).rgb,
diffuseColor.a);
// #fogCode
gl_FragColor = outColor;
}
```
Compile the shader translator, the translator sample, and the shader all
together:
```
./emcc -Iangle/include -Iangle/src angle/samples/translator/translator.cpp angle/src/compiler/preprocessor/*.cpp angle/src/compiler/translator/*.cpp angle/src/compiler/translator/timing/*.cpp angle/src/compiler/translator/depgraph/*.cpp angle/src/third_party/compiler/*.cpp angle/src/common/*.cpp -o translator.html --preload-file aq-fish-nm.frag -s NO_EXIT_RUNTIME=1
```
Serve up the resulting translator.html via `python -m SimpleHTTPServer`.
Navigate the browser to localhost:8000.
The translator sample will run, displaying its output into the text area on the
page. Since it isn't receiving any input, it simply outputs a help message and
exits.
To invoke the translator again, processing the shader we included along with the
source code, open the JavaScript console and type:
```
Module['callMain'](['-s=w', '-u', 'aq-fish-nm.frag'])
```
The active uniforms and their types will be printed to the text area after the
translator sample processes the shader.
# Issues and Next Steps
It's clearly not useful to have to compile the shader in to the
Emscripten-translated executable. It would be helpful to define a simple wrapper
function which can easily be called from JavaScript and which defines enough
parameters to pass in a shader as a string, transform it somehow or compile it
to another language target, and return the compiled result (or other
information). A simple JavaScript library that wraps all of the interactions
with the Emscripten binary would be useful.
It's not feasible to interact with the translator's data structures, nor
traverse the AST from JavaScript. The code that operates upon the shader must be
written in C++ and compiled in to the shader translator.
emcc should be integrated better with ANGLE's build system.
doc/DynamicShaderCompilation.md 0 → 100644
# About
Because ANGLE can only generate full HLSL programs after we known the signatures
between the vertex and pixel stages, we can not immediately call the D3D
compiler at GL shader compile time. Moreover, we can insert additional
optimization code right at draw-time.
ESSL 1.00 shaders treat all vertex inputs as floating point. We insert a
conversion routine to transform un-normalized integer vertex attributes in the
shader preamble to floating point, saving CPU conversion time.
At draw-time, we also optimize out any unused render target outputs. This
improved draw call performance significantly on lower spec and integrated
devices. Changing render target setups may trigger a shader recompile at draw
time.
# Addendum
ANGLE is not the only program to do this kind of draw-time optimization. A
common complaint from application developers is that draw calls sometimes
perform very slowly due to dynamic shader re-compilation. A future design
direction for ANGLE, when targeting a more modern API, is to perform the vertex
conversion in a separate shader pass, which would then be linked with another
compiled shader.
doc/ExtensionSupport.md 0 → 100644
# Introduction
This page details the extensions that are supported by ANGLE.
Specifications for GLES extensions can be found in the [Khronos OpenGL ES API
Registry](http://www.khronos.org/registry/gles/)
Specifications for EGL extensions can be found in the [Khronos EGL API Registry]
(http://www.khronos.org/registry/egl/)
Specifications for ANGLE-specific extensions can be found in the [ANGLE
extension registry]
(https://code.google.com/p/angleproject/source/browse/?name=master#git%2Fextensions)
# Details
## GLES extensions
* GL\_OES\_element\_index\_uint (fn1)
* GL\_OES\_get\_program\_binary
* GL\_OES\_packed\_depth\_stencil
* GL\_OES\_rgb8\_rgba8
* GL\_OES\_standard\_derivatives
* GL\_OES\_texture\_half\_float (fn1)
* GL\_OES\_texture\_half\_float\_linear (fn1)
* GL\_OES\_texture\_float (fn1)
* GL\_OES\_texture\_float\_linear (fn1)
* GL\_OES\_texture\_npot (fn1)
* GL\_EXT\_occlusion\_query\_boolean (fn1)
* GL\_EXT\_read\_format\_bgra
* GL\_EXT\_robustness
* reset notifications and sized queries only, no robust buffer access
* GL\_EXT\_texture\_compression\_dxt1 (fn1)
* GL\_EXT\_texture\_filter\_anisotropic (fn1)
* GL\_EXT\_texture\_format\_BGRA8888
* GL\_EXT\_texture\_storage
* GL\_ANGLE\_depth\_texture
* requires support for INTZ and NULL surfaces in D3D9 (see
http://aras-p.info/texts/D3D9GPUHacks.html)
* GL\_ANGLE\_framebuffer\_blit
* GL\_ANGLE\_framebuffer\_multisample (fn1)
* GL\_ANGLE\_instanced\_arrays
* requires SM3 support
* GL\_ANGLE\_pack\_reverse\_row\_order
* GL\_ANGLE\_texture\_compression\_dxt3 (fn1)
* GL\_ANGLE\_texture\_compression\_dxt5 (fn1)
* GL\_ANGLE\_texture\_usage
* GL\_ANGLE\_translated\_shader\_source
* GL\_NV\_fence (fn1)
## EGL Extensions
* EGL\_EXT\_create\_context\_robustness
* only reset notifications supported
* EGL\_ANGLE\_d3d\_share\_handle\_client\_buffer (fn2)
* EGL\_ANGLE\_query\_surface\_pointer
* EGL\_ANGLE\_software\_display (fn3)
* EGL\_ANGLE\_surface\_d3d\_texture\_2d\_share\_handle (fn2)
* EGL\_NV\_post\_sub\_buffer
### Notes
* fn1: extensions are only exposed if underlying D3D9 device has support for
the required features
* fn2: extensions are only exposed when running on D3D9Ex (ie Win Vista/7)
* fn3: extension is only exposed when swiftshader is present
doc/MANGLE.md 0 → 100644
# M(ulti-platform)ANGLE effort
Starting in early 2014, the ANGLE team has begun work on refactoring the code
with the goal of supporting translation to desktop OpenGL. The new purpose of
ANGLE will be provide a consistent OpenGL ES and EGL context on as many
platforms as possible.
The design doc is available [here]
(https://docs.google.com/document/d/17mxRfzXuEWyvGM3t2KqVY4svvfRj_GzysOEpmnDpqeo/edit?usp=sharing).
doc/ResourceLimits.md 0 → 100644
# Resource Limits
OpenGL ES 2.0 API is quite powerful but there are still some features that are
optional or allow for wide variability between implementations.
Applications that need more than the minimum values for these limits should
query the capabilities of the GL device and scale their usage based on the
device’s feature set. Failing to do so and assuming sufficient limits typically
results in reduced portability.
The various implementation dependent limits can be found in Tables 6.18 – 6.20
of the [OpenGL ES 2.0.25 specification]
(http://www.khronos.org/registry/gles/specs/2.0/es_full_spec_2.0.25.pdf).
# Capabilities
Capability | ES 2.0 Minimum | ANGLE | SM2 | SM3 | SM4+
:----------------------------------------- | :------------- | :--------------- | :---- | :------- | :-------
GL\_MAX\_VERTEX\_ATTRIBS | 8 | 16 | | |
GL\_MAX\_VERTEX\_UNIFORM\_VECTORS | 128 | 254 | | |
GL\_MAX\_VERTEX\_TEXTURE\_IMAGE\_UNITS | 0 | (fn1) | 0 | 0 | 4
GL\_MAX\_VARYING\_VECTORS | 8 | (fn1) | 8 | 10 | 10
GL\_MAX\_FRAGMENT\_UNIFORM\_VECTORS | 16 | (fn1) | 29 | 221 | 221
GL\_MAX\_TEXTURE\_IMAGE\_UNITS | 8 | 16 | | |
GL\_MAX\_TEXTURE\_SIZE | 64 | 2048-16384 (fn1) | | |
GL\_MAX\_CUBE\_MAP\_SIZE | 16 | 2048-16384 (fn1) | | |
GL\_MAX\_RENDERBUFFER\_SIZE | 1 | 2048-16384 (fn1) | | |
GL\_ALIASED\_POINT\_SIZE\_RANGE (min, max) | (1, 1) | (fn2) | (1,1) | (1, fn2) | (1, fn2)
GL\_ALIASED\_LINE\_WIDTH\_RANGE (min, max) | (1, 1) | (1, 1) | | |
## Notes
* fn1: limits vary based on the underlying hardware capabilities
* fn2: on SM3 or better hardware the max point size is D3DCAPS9.MaxPointSize
doc/SourceAccess.md 0 → 100644
# ANGLE Source Code
# Browsing
ANGLE's source no longer resides at code.google.com! To browse the ANGLE source,
please visit https://chromium.googlesource.com/angle/angle
# Checkout
You may clone the ANGLE repository with:
> `git clone https://chromium.googlesource.com/angle/angle`
For full instructions on setting up your system with the necessary prerequisites
for development with ANGLE, please see the DevSetup page.
doc/Update20120704.md 0 → 100644
# ANGLE Development Update - July 4, 2012
We haven't posted an update on the development status of ANGLE in quite some
time and we'd like to provide an update on some of the new features and
improvements that we've been working on.
## Conformance
As announced in the [Chromium Blog]
(http://blog.chromium.org/2011/11/opengl-es-20-certification-for-angle.html),
ANGLE v1.0 has passed the Khronos OpenGL ES 2.0 certification process and is now
a [conformant](http://www.khronos.org/conformance/adopters/conformant-products/)
OpenGL ES 2.0 implementation.
## Extensions
We have recently completed the implementation of depth texture support
([ANGLE\_depth\_texture]
(https://code.google.com/p/angleproject/source/browse/extensions/ANGLE_depth_texture.txt?name=master))
and earlier in the year we added support for instancing via attribute array
divisors ([ANGLE\_instanced\_arrays]
(https://code.google.com/p/angleproject/source/browse/extensions/ANGLE_instanced_arrays.txt?name=master)).
See ExtensionSupport for a complete list of extensions that are supported by
ANGLE.
## Shader Compiler
We have also made a number of improvements in the shader compiler. * We
addressed a number of defects related to scoping differences between HLSL and
GLSL and improved the scoping support in ANGLE's compiler front-end. We also
worked with The Khronos Group to get an ESSL spec bug fixed and several items
clarified. * We addressed a number of correctness issues in the GLSL to HLSL
translation process. We fixed some bugs related to constant propagation and
comma conditional assignments. More importantly, we fully implemented support
for short-circuiting boolean logic operations. In GLSL, Boolean expressions do
short-circuit evaluation as in C, but HLSL evaluates them entirely. This only
has an observable effect if a short-circuited operation has side effects, such
as a function call that modifies global variables. * We implemented detection
for discontinuous gradient or derivative computations inside loops and replace
them with explicitly defined continuous behaviour. HLSL and GLSL differ in their
specified behaviour for operations which compute gradients or derivatives.
Gradients are computed by texture sampling functions which don't specify a
specific mipmap LOD level, and by the OES\_standard\_derivatives built-in
functions. To determine the gradient, the corresponding values in neighbouring
pixels are differentiated. If neighbouring pixels execute different paths
through the shader this can cause a discontinuity in the gradient. GLSL
specifies that in these cases the gradient is undefined. HLSL tries to avoid the
discontinuity in the compiler by unrolling loops so that every pixel executes
all iterations. This can make the D3D HLSL compiler spend a long time generating
code permutations, and possibly even fail compilation due to running out of
instruction slots or registers. Because the GLSL specification allows undefined
behaviour, we can define such texture sampling functions to use mipmap LOD level
0, and have the derivatives functions return 0.0. To do this we examine the GLSL
code's abstract syntax tree and detect whether the shader contains any loops
with discontinuities and gradient operations. Within such loops, we generate
HLSL code that uses explicitly defined texture LODs and derivative information.
One additional consideration is that within these loops there can be calls to
user-defined functions which may contain gradient operations. In this case, we
generate variants of user-defined functions where these operations are
explicitly defined. We use these new functions instead of the original ones in
loops with discontinuities.
These fixes result in ANGLE being able successfully compile a number of the more
complex shaders. Unfortunately there are still some complex shaders which we
have not yet been able to obtain solutions for. Ultimately Direct3D 9 SM3
shaders are more restricted than what can be expressed in GLSL.  Most of the
problematic shaders we've encountered will also not compile successfully on
current ES 2.0 implementations.  We would only be able to achieve parity with
Desktop GL implementations by using Direct3D 10 or above.
## Texture Origin Changes
We have also made a major change to ANGLE in the way the origin difference
between D3D and OpenGL is handled. This difference is normally observable when
using render-to-texture techniques, and if not accounted for, it would appear
that images rendered to textures are upside down. In recent versions of ANGLE
(r536 (on Google Code)-r1161 (on Google Code)), we have been storing surfaces
following the D3D Y convention where (0, 0) is the top-left, rather than GL's
bottom-left convention. This was done by vertically flipping textures on load
and then adjusting the texture coordinates in the shaders to compensate. This
approach worked well, but it did leave the orientation of pbuffers inverted when
compared to native GL implementations. As of ANGLE r1162 (on Google Code), we
have changed this back to the original way it was implemented - textures are
loaded and stored in the GL orientation, and the final rendered scene is flipped
when it is displayed to a window by eglSwapBuffers. This should be essentially
transparent to applications except that orientation of pbuffers will change.  In
addition to fixing the pbuffer orientation, this change: * eliminates
dependent-texture look-ups in the shaders, caused by flipping the texture
y-coordinates, * rounding of texture coordinates (while previously within spec)
will be more consistent with other implementations, and * allows potential
faster paths for loading texture data to be implemented. The only potential
downside to this approach is that window-based rendering may be a bit slower for
simple scenes. The good news is that this path is not used by browser
implementations on most versions of Windows.
## Preprocessor
Finally, Alok P. from Google has been working on implementing a new shader
preprocessor for the last number of months and this effort is nearly complete.
This new preprocessor should be more robust and much more maintainable. It also
includes many (~5000) unit tests and passes all WebGL conformance tests. If you
wish to try this out before it is enabled by default, define
ANGLE\_USE\_NEW\_PREPROCESSOR=1 in your project settings for the
translator\_common project.
## Contributions
As always we welcome contributions either in the bug reports (preferably with an
isolated test-case) or in the form of code contributions. We have added a
[ContributingCode](ContributingCode.md) wiki page documenting the preferred
process for contributing code. We do need to ask that you sign a Contributor
License Agreement before we can integrate your patches.
doc/Update20130618.md 0 → 100644
# ANGLE Development Update - June 18, 2013
This week brings some significant changes to ANGLE, which we think are worth
covering in a development update.
## Migration from svn to git
We've changed our backing version control system from svn to git. Projects and
contributors pulling from the svn repository will continue to be able to do so,
but please note that this repository is now read-only, and no further updates
will be made there. To continue tracking new development and issue fixes, you'll
need to watch the git repository. Instructions on checking out code from the git
repository can be found on the [Source Checkout]
(https://code.google.com/p/angleproject/source/checkout) page.
## DirectX 11 Support
ANGLE now provides both a DirectX 9 and a DirectX 11-backed renderer in the same
code base. By default, support for the DirectX 11 renderer is disabled, but it
can be enabled by toggling the value of ANGLE\_ENABLE\_D3D11 as described on the
DevSetup page. On systems without DirectX 11 support, ANGLE will fall back to
DirectX 9.
This work originally appeared in our dx11proto branch, which, with the move to
the new repository, has been promoted to master. Code previously located in the
trunk of the svn repository will now be located in the git legacy branch, and
active development will now move to the newly promoted master.
doc/Update20131120.md 0 → 100644
# ANGLE Development Update - November 20, 2013
ANGLE has undergone a few further migrations in the past week, which we thought
it important to mention in a front-page update.
The review process for contributed code has moved from [Rietveld]
(https://codereview.appspot.com/) to [Gerrit]
(https://chromium-review.googlesource.com). This migration allows us to more
easily support a Git-centric workflow, and eases the process of accepting
changes submitted by contributors without commit access to our repositories.
As a result of this change, our repository has also moved from its prior
location at code.google.com to https://chromium.googlesource.com/angle/angle.
The repository may still be pulled from its old location, but no further changes
will be committed there. Updates will be made only to the repository's new
location.
doc/Update20140325.md 0 → 100644
# ES 3.0 Development Branch merging
ANGLE will soon be merging its ES 3.0 development branch to master, to make
available (and more visible) the changes we've been making over the past several
months in support of ES 3.0, and to remove divergence between the master and
development branches.
The previous master branch will still be available as the es2only-legacy branch,
and SHAs will not change, so dependencies on individual commits of ANGLE will
continue to work as expected. However, new contributions against es2only-legacy
will generally not be considered, and future work should be done on master.
This merge doesn't signify completion of ES 3.0, as we have some features still
left to implement there, but interested developers can explore the work in
progress. A significant portion of 3.0 features have been implemented,
including: * 2D array textures, 3D textures * Expanded texture format support *
Uniform Buffer Objects * Vertex Array Objects * Sampler objects, expanded
sampler types * Transform Feedback * Texture Swizzle * GLSL integer support
ES 3.0 features should not yet be considered stable, even where implemented, and
some features are present only via naive implementation so far. There is still
quite a bit of work ahead of us before ES 3.0 support is complete, but this
merge should provide insight to those interested in what we've been working on!
doc/Update20150105.md 0 → 100644
# Multiplatform ANGLE Refactor Complete
ANGLE's multiplatform refactoring effort ([described here]
(https://code.google.com/p/angleproject/wiki/MANGLE)) is now complete, paving
the way for additional rendering backends, allowing ANGLE to enable OpenGL ES
not just over Direct3D 9 and 11, but also desktop OpenGL.
The refactoring we've done encapsulates D3D-related assumptions and API calls at
the renderer level, so that no D3D calls are made in the renderer-agnostic
portions of the codebase, and D3D-specific feature implementations won't be
included on non-D3D platforms. For example, the creation and maintenance of
CPU-side copies of texture data, which are required to enable GL-style
per-mip-level texture creation over D3D's entire-mipchain texture creation API,
is contained entirely within the D3D renderers, allowing a GL implementation to
avoid this complication.
Work will now begin within ANGLE to add a desktop OpenGL renderer, and EGL
implementations compatible with OS X and Linux.
# ES 3.0 Development Status
Our ES 3.0 development branch was merged into mainline ANGLE in April 2014, but
ES 3.0 support is not yet complete. The majority of API functionality has been
implemented; features still pending include: * ETC2/EAC support * primitive
restart index * drawRangeElements * full GetProgramBinary support in core
Additional work remains in the compiler, including: * Array .length() * inf/nan
detection * math utility functions, rounding * VertexID/InstanceID support *
floating point packing functions * operators new in ES 3.0 * name redeclaration
* relaxed array indexing * switch statement support * loop & iteration
improvements
ES 3.0 features should not be considered stable, even where implemented, and
some features are present only via naive implementation so far, but we welcome
bugs filed against this functionality, and thank all our contributors!
doc/VTF.md 0 → 100644
# Vertex Texture Fetch
This page details the steps necessary to implement vertex texture fetch in ANGLE
and documents some of the pitfalls that may be encountered along the way.
# Details
Tasks to implement vertex texture support.
1. add/enable vertex shader texture look up functions in compiler & HLSL
translator.
* add texture2DLod, texture2DProjLod (2 variants), textureCubeLod (these
are **only** valid in vertex shaders)
* ensure other (non-bias/non-LOD) texture functions work in vertex shaders
* non-mipmapped textures use the only level available
* mipmapped textures use only the base level (ie level 0).
2. update implementation-dependant constants in Context.h
* MAX\_VERTEX\_TEXTURE\_IMAGE\_UNITS = 4
* MAX\_COMBINED\_TEXTURE\_IMAGE\_UNITS =
MAX\_VERTEX\_TEXTURE\_IMAGE\_UNITS + MAX\_TEXTURE\_IMAGE\_UNITS (ie 20).
* these limits have to change based on the d3d device characteristics. For
example we likely don't want to advertise vertex image units on SM2.0
cards (unless we end up using software vertex processing).
* detection of hardware support for various formats, types, etc.
* As a first pass, use the "hasVertexTextures" check that Aras suggested
to only enable VTF on DX10 NVIDIA and AMD parts, and SM3 Intel parts.
* If this proves insufficient, there are other things we can do, but it
involves using software vertex processing for unsupported formats and
system memory copies of textures -- all stuff which is rather annoying
and likely to hurt performance (see point 4. below).
3. add support and handling for vertex textures/samplers in the API.
* any textures used in a vertex shader need to get assigned to the special
samplers in d3d9
* there are only 4 of them (D3DVERTEXTEXTURESAMPLER0..
D3DVERTEXTEXTURESAMPLER3)
* if a texture is used in both vertex & fragment it counts twice against
the "MAX\_COMBINED" limit (validated in Program::validateSamplers)
* there are a number of places in our code where we have arrays of size,
or iterate over, MAX\_TEXTURE\_IMAGE\_UNITS. These will need to be
changed to operate on MAX\_COMBINED\_TEXTURE\_IMAGE\_UNITS instead. A
(possibly incomplete & outdated) list of areas that need to be updated
is as follows:
* Program.h - increase size of mSamplers
* Context.h - increase size of samplerTexture
* glActiveTexture needs accept values in the range
0..MAX\_COMBINED\_TEXTURE\_IMAGE\_UNITS-1
* Context::~Context
* GetIntegerv (2D\_BINDING, CUBE\_BINDING)
* Context::applyTextures
* Context::detachTexture
* Program::getSamplerMapping
* Program::dirtyAllSamplers
* Program::applyUniform1iv
* Program::unlink
* Program::validateSamplers
4. handling the nasty corner cases: texture formats, filtering and cube
textures.
* OpenGL doesn't provide any restrictions on what formats and/or types of
textures can used for vertex textures, or if filtering can be enabled,
whereas D3D9 does.
* Reference Rasterizer / Software Vertex Processing: all formats & types
supported (including filtering)
* ATI R500 (on Google Code) cards do not support VTF (even though they are
SM 3.0)
* ATI R600 (on Google Code) (and later) and in theory the Intel 965+,
claim to support all texture formats/types we care about and some with
filtering
* NVIDIA cards fall into two camps:
* dx9 SM3 (6&7 series): only R32F & A32B32G32R32F supported for 2D and no
filtering, CUBE or VOL texture support
* dx10 (8+ series): only float texture formats for 2D, CUBE & VOLUME. no
filtering (according to caps)
* further info from Aras P. suggests that all formats are supported on
DX10 hardware, but are just not advertised.
* unsure what they do on these cards under OpenGL. Need to do more
testing, but suspect software fallback.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment