Move the most popular wiki articles into markdown files.

Change-Id: Ide6ef3d9995d1f3f66de4b340a60b4bf350a9ddb
Reviewed-on: https://chromium-review.googlesource.com/275479
Reviewed-by: Shannon Woods <shannonwoods@chromium.org>
Reviewed-by: Jamie Madill <jmadill@chromium.org>
Tested-by: Geoff Lang <geofflang@chromium.org>

README.md

@@ -8,13 +8,13 @@ ANGLE is used as the default WebGL backend for both Google Chrome and Mozilla Fi
 Portions of the ANGLE shader compiler are used as a shader validator and translator by WebGL implementations across multiple platforms. It is used on Mac OS X, Linux, and in mobile variants of the browsers. Having one shader validator helps to ensure that a consistent set of GLSL ES shaders are accepted across browsers and platforms. The shader translator can be used to translate shaders to other shading languages, and to optionally apply shader modifications to work around bugs or quirks in the native graphics drivers. The translator targets Desktop GLSL, Direct3D HLSL, and even ESSL for native GLES2 platforms.
 
 ##Building
-For building instructions, visit the [dev setup wiki](https://code.google.com/p/angleproject/wiki/DevSetup).
+View the [Dev setup instructions](doc/DevSetup.md).
 
 ##Contributing
 * Join our [Google group](https://groups.google.com/group/angleproject) to keep up to date.
 * Join us on IRC in the #ANGLEproject channel on FreeNode.
-* Read about ANGLE development on the [wiki](http://code.google.com/p/angleproject/w/list).
+* Read about ANGLE development in our [documentation](doc).
-* Become a [code contributor](https://code.google.com/p/angleproject/wiki/ContributingCode).
+* Become a [code contributor](doc/ContributingCode.md).
 * File bugs in the [issue tracker](http://code.google.com/p/angleproject/issues/list) (preferably with an isolated test-case).
 * Read about WebGL on the [Khronos WebGL Wiki](http://khronos.org/webgl/wiki/Main_Page).
 * Learn about implementation details in the [OpenGL Insights chapter on ANGLE](http://www.seas.upenn.edu/~pcozzi/OpenGLInsights/OpenGLInsights-ANGLE.pdf) and this [ANGLE presentation](https://code.google.com/p/angleproject/downloads/detail?name=ANGLE%20and%20Cross-Platform%20WebGL%20Support.pdf&can=2&q=).

doc/BuildingAngleForChromiumDevelopment.md

@@ -0,0 +1,73 @@
+# How to build ANGLE in Chromium for dev
+
+## Introduction
+
+ANGLE is normally built on Windows but parts of it are cross platform including the shader validator and translator. These parts can be built and tested inside a Chromium checkout.
+
+## Details
+
+Steps:
+
+  * Checkout and build [Chromium](http://dev.chromium.org/Home).
+  * To setup run these commands (note similarity to [DevSetup](DevSetup.md)):
+
+```bash
+cd src/third_party/angle
+gclient config --name . --unmanaged https://chromium.googlesource.com/angle/angle.git
+
+gclient sync
+git checkout master
+```
+
+  * To make the build files run these commands
+
+```bash
+cd src/third_party/angle
+GYP_GENERATORS=ninja gclient runhooks
+```
+
+  * To build
+
+```bash
+cd src/third_party/angle
+ninja -j 10 -k1 -C out/Debug
+```
+
+  * To build a specific target add the target at the end:
+
+```bash
+cd src/third_party/angle
+ninja -j 10 -k1 -C out/Debug angle_compiler_tests
+```
+
+  * To run
+
+```bash
+cd src/third_party/angle
+./out/Debug/angle_compiler_tests
+```
+
+## Working with Top of Tree ANGLE in Chromium
+
+If you're actively developing within ANGLE in your Chromium workspace you will want to work with top of tree ANGLE. To do this do the following:
+
+  * Ignore ANGLE in your `.gclient`
+
+```python
+solutions = [
+  {
+    # ...
+    u'custom_deps':
+    {
+      "src/third_party/angle": None,
+    },
+  },
+]
+```
+
+You then have full control over your ANGLE workspace and are responsible for running all git commands (pull, rebase, etc.) for managing your branches.
+
+If you decide you need to go back to the DEPS version of ANGLE:
+  * Comment out the `src/third_party/angle` line in your `custom_deps`.
+  * Go into your ANGLE workspace and switch back to the master branch (ensure there are no modified or new files).
+  * `gclient sync` your Chromium workspace.

doc/CodeReviewProcess.md

@@ -0,0 +1,27 @@
+# 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).
+
+## 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!
+
+ 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/).
+ 2. Review the change listed by looking over the diffs listed in the most recent patch set.
+    * You may view the diffs either side-to-side, or in unified diff format.
+    * 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.
+    * 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.
+ 3. Once your review is complete, click the "Review" button
+    * If you are satisfied with the change list as it is, give a positive review (Code-Review +1 or +2).
+    * If you think the change list is a good idea, but needs changes, leave 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/ContributingCode.md

@@ -0,0 +1,83 @@
+# Contributing Code
+
+If you want to contribute code to ANGLE, there are a few things you can do to make the process flow smoothly.  These are based on the [Chromium Projects: Contributing Code](http://www.chromium.org/developers/contributing-code/) guidelines.
+
+## Communicate
+
+ * Whether you're writing a new feature or fixing an existing bug, it pays to get a second opinion before you get too far. If it's a new feature idea, post to the discussion group ([angleproject](https://groups.google.com/forum/?fromgroups#!forum/angleproject)) and propose it or talk with the ANGLE team on IRC in the #ANGLEproject channel on FreeNode.
+ * Not all bugs in our [bug system](https://code.google.com/p/angleproject/issues/list) are assigned, but if the one you're interested in fixing is, send a note to the person it's assigned to and ask if they would like a patch.
+ * Behavior changes and anything nontrivial (i.e. anything other than simple cleanups and style fixes) should generally be tracked in the bug system. Please [file a bug](https://code.google.com/p/angleproject/issues/entry) and describe what you're doing if there isn't one already.
+
+## Get your code ready
+### Code
+ 1. Must conform to the [CodingStandard ANGLE style] guidelines.
+ 2. Must be tested. (see the 'Testing' section below)
+ 3.  Should be a reasonable size to review.  Giant patches are unlikely to get reviewed quickly.
+
+### Build maintenance
+ 1. If you added or removed source files:
+    * You _must_ update the gyp build scripts lists with your changes. See `src/libEGL.gypi`, `src/libGLESv2.gypi`, and `src/compiler.gypi`.
+ 2. ANGLE also now maintains a BUILD.gn script for  [Chromium's gn build](https://code.google.com/p/chromium/wiki/gn).  If you changed the gyp files other than to add or remove new files, you will also need to update BUILD.gn. Ask a project member for help with testing if you don't have a Chromium checkout.
+ 3. If you modified `glslang.y` or `glslang.l`:
+    * You _must_ update the bison-generated compiler sources. Download and install the latest 64-bit Bison in [https://cygwin.com/install.html Cygwin]. From the Cygwin shell run `generate_parser.sh` in `src/compiler/translator` and update your CL. Do not edit the generated files by hand.
+    * If you modified `ExpressionParser.y` or `Tokenizer.l`, follow the same process by running `src/compiler/preprocessor/generate_parser.sh`.
+### Testing
+ * Your must test your new code, and ensure there are no regressions with the ANGLE required tests:
+    * `angle_unittests` must have no failures on Windows.
+    * `angle_end2end_tests` must have no failures on Windows.
+    * No new failures in the [Top-of-Tree WebGL Conformance tests](https://www.khronos.org/registry/webgl/sdk/tests/webgl-conformance-tests.html) on Windows.
+      * If you are a Chromium developer, see [Building ANGLE for Chromium Development](BuildingAngleForChromiumDevelopment.md) for instructions on building ANGLE within Chromium
+      * If you aren't a browser developer, you should be able to drop your compiled DLLs into a Chrome installation, in place of those distributed with Chrome, to check WebGL conformance. [Chrome Canary](https://www.google.com/chrome/browser/canary.html) is well-suited for this.
+      * Your failures must be a subset of the expected WebGL failures located in [`src/tests/WebGL-CTS-known-failures.txt`](../src/tests/WebGL-CTS-known-failures.txt). If you believe there are failing tests missing from the known failures file, please notify project members.
+   * If your code isn't covered by an existing test, you are *strongly encouraged* to add new test coverage. This both ensures that your code is correct and that new contributors won't break it in the future.
+   * If you are submitting a performance fix, test your code with `angle_perftests` and add a new performance test if it is not covered by the existing benchmarks.
+   * We don't require testing on non-Windows platforms, but ANGLE tests compile and runs on Mac, Linux, ChromeOS and more. Watch the [Chromium GPU FYI bot waterfall](http://build.chromium.org/p/chromium.gpu.fyi/console) for build breaks and notify a project member if you see one!
+   * ANGLE also includes the [drawElements Quality Program (dEQP)](dEQP.md) for additional testing. If you're working on a new feature, there may be some extensive tests for it already written.
+### Legal
+ 1. You must complete the [Individual Contributor License Agreement](http://code.google.com/legal/individual-cla-v1.0.html). You can do this online, and it only takes a minute. If you are contributing on behalf of a corporation, you must fill out the [Corporate Contributor License Agreement](http://code.google.com/legal/corporate-cla-v1.0.html) and send it to Google as described on that page.
+ 2. Once you've submitted the CLA, please email the following information (as entered on the CLA) to `shannonwoods at chromium dot org` for record keeping purposes:
+    * Full Name:
+    * Email:
+    * Company (If applicable):
+ 3. If you've never submitted code before, you must add your (or your organization's) name and contact info to the [AUTHORS](../AUTHORS) file.
+ 4. *NOTE TO REVIEWERS*: Follow the [External Contributor Checklist](http://www.chromium.org/developers/contributing-code/external-contributor-checklist).
+
+## Life of a Change List
+We use the [Gerrit](http://code.google.com/p/gerrit) open source code review tool. The process is similar, but not identical, to the one used by ChromiumOS, described here: [http://www.chromium.org/chromium-os/developer-guide/gerrit-guide](http://www.chromium.org/chromium-os/developer-guide/gerrit-guide).
+
+### Getting started with Gerrit for ANGLE
+  1. Go to [https://chromium-review.googlesource.com/new-password](https://chromium-review.googlesource.com/new-password)
+  2. Log in with the email you use for your git commits.
+  3. Follow the directions on the new-password page to set up authentication with your Google account.
+  4. Make sure to set your real name.
+     * Visit [https://chromium-review.googlesource.com/#/settings](https://chromium-review.googlesource.com/#/settings) and check the "Full Name" field.
+  5. Check out the repository (see [DevSetup](DevSetup.md)).
+  6. Install the Gerrit `commit_msg` hook
+     * Gerrit requires a hook to append a change ID tag to each commit, so that it can associate your CL with a particular review, and track dependencies between commits.
+     * Download the hook from [https://chromium-review.googlesource.com/tools/hooks/commit-msg](https://chromium-review.googlesource.com/tools/hooks/commit-msg) and copy this file to `.git/hooks/commit-msg` within your local repository. On non-Windows, platforms, ensure that permissions are set to allow execution.
+     * *BE AWARE:* Some patch management tools, such as StGit, currently bypass git hooks. They should not currently be used with changes intended for review.
+
+### Making changes
+ 1. Commit your changes locally:
+    * `git add src/../FileName.cpp`
+    * `git commit`
+    * A text editor will open. Add a description at the top of the file.
+       * If your changes are associated with an issue in the issue tracker (e.g. a fix for a reported bug), please associate the CL with that issue by adding the following line to the commit message: `BUG=angleproject:<issue number>`.
+    * Save.
+    * Close the text editor.
+    * Use `git commit --amend` to update your CL with new changes.
+ 2. Upload the change list
+    * `git cl upload`
+    * The change list and modified files will be uploaded to Gerrit.
+    * Follow the generated URL to the new issue.
+    * Take a moment to perform a self-review of your code. Gerrit's viewer makes it easy to see whitespace errors, erroneous tabs, and other simple style problems.
+    * Designate reviewers-- if you don't do this, reviewers may not realize you're requesting a review!
+      * If you don't know who to use, select either `geofflang at chromium dot org` or `jmadill at chromium dot org`.
+    * Make changes, upload and repeat as necessary.
+    * Project members and others will review your code as described in the CodeReviewProcess.
+ 3. If your change list needs revision:
+    * If you have correctly installed the commit hook from the section above, Gerrit will be able to track your changes by Change-Id.
+    * You should need only to update your commit with `git commit --amend` and re-upload with `git cl upload`.
+4. Once your code is reviewed:
+    * If you are a committer, you may submit the change yourself via the Gerrit web interface.
+    * If you are not a committer, ask your reviewer to submit the change list.

doc/DevSetup.md

@@ -0,0 +1,79 @@
+# ANGLE Development
+
+ANGLE provides OpenGL ES 2.0 and EGL 1.4 libraries and dlls.  You can use these to build and run OpenGL ES 2.0 applications on Windows.
+
+## Development setup
+
+### Version Control
+ANGLE uses git for version control. If you are not familiar with git, helpful documentation can be found at [http://git-scm.com/documentation](http://git-scm.com/documentation).
+
+### Required Tools
+ * [Visual Studio Community 2013](http://www.visualstudio.com/downloads/download-visual-studio-vs)
+   * Required to build ANGLE on Windows and for the packaged Windows 8.1 SDK.
+ * [depot_tools](http://dev.chromium.org/developers/how-tos/install-depot-tools)
+   * Required to generate projects and build files, contribute patches, run the unit tests or build the shader compiler on non-Windows systems.
+ * [Cygwin's Bison, flex, and patch](https://cygwin.com/setup-x86_64.exe) (optional)
+   * This is only required if you need to modify GLSL ES grammar files (`glslang.l` and `glslang.y` under `src/compiler/translator`, or `ExpressionParser.y` and `Tokenizer.l` in `src/compiler/preprocessor`).
+   * Use the latest versions of bison, flex and patch from the 64-bit cygwin distribution.
+
+### Getting the source
+Set the following environment variables as needed:
+ * `GYP_GENERATORS` to `msvs` (other options include `ninja` and `make`)
+ * `GYP_DEFINES` to `windows_sdk_path=YOUR_WIN_SDK_INSTALL_DIR` if you did not install the Windows 8.1 SDK in the default location.
+ * `GYP_MSVS_VERSION` to `2013` (or `2013e` for Express editions of MSVS)
+Download the ANGLE source by running the following commands:
+```
+mkdir angle
+cd angle
+gclient config --name . --unmanaged https://chromium.googlesource.com/angle/angle.git
+gclient sync
+git checkout master
+```
+Gyp will generate the main VS2013 solution file as build/ANGLE.sln. If you update ANGLE, or make a change to the projects, they can be regenerated by executing `gclient runhooks`.
+
+### Building ANGLE
+ 1. Open one of the ANGLE Visual Studio solution files (see [Getting the Source](Getting the source)).
+ 2. Select Build -> Configuration Manager
+ 3. In the "Active solution configuration:" drop down, select the desired configuration (eg. Release), and close the Configuration Manager.
+ 4. Select Build -> Build Solution.
+Once the build completes, the output directory for your selected configuration (eg. `Release_Win32`, located next to the solution file) will contain the required libraries and dlls to build and run an OpenGL ES 2.0 application.
+
+## Application Development with ANGLE
+This sections describes how to use ANGLE to build an OpenGL ES application.
+
+### Choosing a D3D Backend
+ANGLE can use either a backing renderer which uses D3D11 on systems where it is available, or a D3D9-only renderer.
+
+ANGLE provides an EGL extension called `EGL_ANGLE_platform_angle` which allows uers to select which renderer to use at EGL initialization time by calling eglGetPlatformDisplayEXT with special enums. Details of the extension can be found in it's specification in `extensions/ANGLE_platform_angle.txt` and `extensions/ANGLE_platform_angle_d3d.txt` and examples of it's use can be seen in the ANGLE samples and tests, particularly `util/EGLWindow.cpp`.
+
+By default, ANGLE will use a D3D11 renderer. To change the default:
+ 1. Open `src/libANGLE/renderer/d3d/DisplayD3D.cpp`
+ 2. Locate the definition of `ANGLE_DEFAULT_D3D11` near the head of the file, and set it to your preference.
+
+### To Use ANGLE in Your Application
+ 1. Configure your build environment to have access to the `include` folder to provide access to the standard Khronos EGL and GLES2 header files.
+  * For Visual C++
+     * Right-click your project in the _Solution Explorer_, and select _Properties_.
+     * Under the _Configuration Properties_ branch, click _C/C++_.
+     * Add the relative path to the Khronos EGL and GLES2 header files to _Additional Include Directories_.
+ 2. Configure your build environment to have access to `libEGL.lib` and `libGLESv2.lib` found in the build output directory (see [DevSetup#Building_ANGLE]).
+   * For Visual C++
+     * Right-click your project in the _Solution Explorer_, and select _Properties_.
+     * Under the _Configuration Properties_ branch, open the _Linker_ branch and click _Input_.
+     * Add the relative paths to both the `libEGL.lib` file and `libGLESv2.lib` file to _Additional Dependencies_, separated by a semicolon.
+ 3. Copy `libEGL.dll` and `libGLESv2.dll` from the build output directory (see [Building ANGLE](Building ANGLE)) into your application folder.
+ 4. Code your application to the Khronos [OpenGL ES 2.0](http://www.khronos.org/registry/gles/) and [EGL 1.4](http://www.khronos.org/registry/egl/) APIs.
+
+## GLSL ES to GLSL Translator
+In addition to OpenGL ES 2.0 and EGL 1.4 libraries, ANGLE also provides a GLSL ES to GLSL translator. This is useful for implementing OpenGL ES emulators on top of desktop OpenGL.
+
+### Getting the source
+The translator code is fully independent of the rest of ANGLE code and resides in `src/compiler`.  It is cross-platform and build files for operating systems other than Windows can be generated by following the `Generating project files` steps above.
+
+### Usage
+The basic usage is shown in `essl_to_glsl` sample under `samples/translator`. To translate a GLSL ES shader, following functions need to be called in the same order:
+ * `ShInitialize()` initializes the translator library and must be called only once from each process using the translator.
+ * `ShContructCompiler()` creates a translator object for vertex or fragment shader.
+ * `ShCompile()` translates the given shader.
+ * `ShDestruct()` destroys the given translator.
+ * `ShFinalize()` shuts down the translator library and must be called only once from each process using the translator.

doc/dEQP.md

@@ -0,0 +1,35 @@
+# ANGLE + dEQP
+drawElements (dEQP) is a very robust and comprehensive set of open-source tests for GLES2, GLES3+ and EGL. They provide a huge net of coverage for almost every GL API feature. ANGLE by default builds dEQP testing targets for testing with GLES 2 with D3D9/11 and OpenGL, and GLES 3 with D3D11.
+
+## How to build dEQP
+
+You should have dEQP as a target if you followed the [DevSetup](DevSetup.md) instructions. There are two executables, `angle_deqp_gles2_tests` and `angle_deqp_gles3_tests`.
+
+Currently we only support Windows platforms.
+
+## How to use dEQP
+
+Running the full test suite in Debug can take a very long time. We recommend first dumping the complete lists of tests to a text file, then running the tests that apply to your changes.
+
+### Dump the case list
+
+To dump a list of test cases, append the command line arguments `--deqp-runmode=txt-caselist`, run the GLES2 or GLES3 target, then look for the file named `src\tests\third_party\deqp\data\dEQP-GLES2-cases.txt`. (Or GLES3).
+
+### Choose your tests
+
+Scan the case list files for tests with names similar to the features you're working on. Then, to run particular tests, use the command line arguments `--deqp-case=dEQP-GLES2.functional.shaders.linkage.*` (for example). Replace the test name string with the test your want from the case list files you dumped above.
+
+### Choose a Renderer
+
+By default the tests run on ANGLE D3D11. To specify the exact platform for ANGLE + dEQP, use the arguments:
+
+  * `--deqp-egl-native-display-type=angle-d3d11` for D3D11 (high feature level)
+  * `--deqp-egl-native-display-type=angle-d3d9` for D3D9
+  * `--deqp-egl-native-display-type=angle-d3d11-fl93` for D3D11 Feature level 9_3
+  * `--deqp-egl-native-display-type=angle-gl` for OpenGL
+
+### Check your results
+
+For now, the recommended practice is to manually compare your passes/failures with the results prior to your modifications.
+
+dEQP uses the open-source GUI [Cherry](https://android.googlesource.com/platform/external/cherry) for viewing batch test results (see the `TestResults.qpa` file). ANGLE doesn't currently build or distribute Cherry, but feel free to check it out!