Add Orientation and Starter-Projects docs

README.md

@@ -55,6 +55,7 @@ View the [Dev setup instructions](doc/DevSetup.md).
 
 * 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.
+* Join us on [Slack](https://chromium.slack.com) in the #angle channel.
 * [File bugs](http://anglebug.com/new) in the [issue tracker](https://bugs.chromium.org/p/angleproject/issues/list) (preferably with an isolated test-case).
 * [Choose an ANGLE branch](doc/ChoosingANGLEBranch.md) to track in your own project.
 
@@ -66,6 +67,7 @@ View the [Dev setup instructions](doc/DevSetup.md).
 * Use ANGLE's [coding standard](doc/CodingStandard.md).
 * Learn how to [build ANGLE for Chromium development](doc/BuildingAngleForChromiumDevelopment.md).
 * Get help on [debugging ANGLE](doc/DebuggingTips.md).
+* Go through [ANGLE's orientation](doc/Orientation.md) and sift through [starter projects](doc/Starter-Projects.md).
 
 
 * Read about WebGL on the [Khronos WebGL Wiki](http://khronos.org/webgl/wiki/Main_Page).

doc/Orientation.md

+# ANGLE Orientation
+
+A basic guide to get up and running fixing bugs and performance issues in ANGLE.
+
+## First ANGLE Compile
+
+### Windows
+
+- Download and install
+  [Visual Studio 2017 Community](https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx).
+  Installing takes some time.
+
+- Take the time to register a Microsoft account, otherwise you'll get nagged to death.
+
+- Download and install Chromium's
+  [depot_tools](http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up)
+  for building ANGLE.
+
+- Add the `depot_tools` dir to your system path. Open start menu, type "edit environment variables",
+  add it to PATH.
+
+- (recommended) Download and install [Git for Windows](http://gitforwindows.org/).
+
+- Open Git bash, head to C:/src and follow the steps on
+  [the ANGLE wiki](https://chromium.googlesource.com/angle/angle/+/master/doc/DevSetup.md#Development-setup-Getting-the-source)
+  to set up the ANGLE solution for the first time.
+
+- The VS 2017 solution will be in `c:/src/angle/out/sln/ANGLE.sln`. Open and let the installation
+  finish.  **Important**: set indent style to spaces, not tabs!
+
+- Building should work at this point!
+
+- Try running `angle_end2end_tests`, `angle_unittests` or a sample program.
+
+- Useful VS extensions:
+
+  1. [Build Only Startup Project](https://marketplace.visualstudio.com/items?itemName=SenHarada.BuildOnlyStartupProject)
+  2. [SwitchStartupProject](https://marketplace.visualstudio.com/items?itemName=vs-publisher-141975.SwitchStartupProject)
+  3. [Smart CommandLine Arguments](https://www.visualstudiogallery.msdn.microsoft.com/535f79b1-fbe0-4b0a-a346-8cdf271ea071)
+
+### Linux
+
+- Download and install Chromium's
+  [depot_tools](http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up)
+  for building ANGLE.
+
+- Ensure you add `depot_tools` to your bashrc as in the wiki link above.
+
+- Follow the steps on
+  [the ANGLE wiki](https://chromium.googlesource.com/angle/angle/+/master/doc/DevSetup.md#Development-setup-Getting-the-source)
+  to setup ANGLE's build.
+
+- Building should work at this point! Follow the steps on the Wiki.
+
+- Try running `angle_end2end_tests`, `angle_unittests` or a sample program.
+
+## Setting up the [drawElements testing suite](http://go/dEQP)
+
+- [Cherry](https://sites.google.com/a/google.com/deqp/cherry) is the UI for viewing test results.
+  ANGLE checks out a copy in `<angledir>/third_party/cherry`.
+
+- Follow the instructions in the
+  [installation README](https://android.googlesource.com/platform/external/cherry/+/refs/heads/master/README)
+  to get it running. On Windows, use 64-bit.
+
+- Read up on testing with
+  [dEQP on the ANGLE Wiki](https://chromium.googlesource.com/angle/angle/+/master/doc/dEQP.md).
+
+- Try running `angle_deqp_gles2_tests_no_gtest` with the flag
+  `--deqp-case=dEQP-GLES2.functional.negative_api.*` and load a test report in Cherry.
+
+- To use Cherry, browse to [http://localhost:8080/#/results](http://localhost:8080/#/results) and
+  click '**Import existing batch**', loading `TestResults.qpa`.  Look for the qpa file in the
+  current working directory, or `<angledir>/src/tests` if you ran the tests from Visual Studio.
+
+- Note: we only use Cherry for viewing test output, not running the tests. On start, you may see
+  some runtime messages about unable to load case lists. These are safe to ignore. If you didn't
+  load the results URL directly, click the "**Results**" tab to find the Import button.
+
+## Profiling
+
+- You can use `scripts/perf_test_runner.py` to run any target of `./angle_perftests` (see script
+  source for details).
+
+### With Visual Studio
+
+- In Visual Studio 2017, look under Debug/Profiler/Performance Explorer/New Performance Session.
+  Right-click "Targets" and add `angle_perftests` as a Target Project.
+
+- Run `angle_perftests` with the flag `--gtest_filter=DrawCallPerfBenchmark.Run/d3d11_null` for
+  D3D11, `.../d3d9_null` for D3D9, `.../gl_null` for OpenGL and `.../vulkan_null` for Vulkan.
+
+- Make sure you close all open instances of Chrome, they use a lot of background CPU and GPU. In
+  fact, close every process and application you can.
+
+### Profiling with Visual Studio + Chrome
+
+- Install [Chrome Canary](https://www.google.com/chrome/browser/canary.html).
+
+- Canary's install dir is usually `%APPDATA%/Local/Google/Chrome SxS/Application`
+
+- Build ANGLE x64, Release, and run 'python scripts/update_canary_angle.py' to replace Canary's
+  ANGLE with your custom ANGLE. (Note: Canary must be closed)
+
+- Start Canary with `--gpu-startup-dialog --disable-gpu-sandbox`, wait for the dialog.
+
+- In Visual Studio, under Debug/Profiler, choose attach to process.
+
+- Attach to the Chrome GPU process, then immediately pause profiling.
+
+- **IMPORTANT:** Verify ANGLE details are correct in `about:gpu`.
+
+- In Canary, start your benchmark, then resume profiling, and exit when done. The report will load
+  automatically.
+
+## Bookmark the latest Khronos specs
+
+- [The GLES 2.0 Spec](https://www.khronos.org/registry/OpenGL/specs/es/2.0/es_full_spec_2.0.pdf)
+
+- [The GLES 3.0 Spec](https://www.khronos.org/registry/OpenGL/specs/es/3.0/es_spec_3.0.pdf)
+
+- [The GLES 3.1 Spec](https://www.khronos.org/registry/gles/specs/3.1/es_spec_3.1.pdf)
+
+- [The GLES Shading Language 1.00 Spec](https://www.khronos.org/files/opengles_shading_language.pdf)
+
+- [The GLES Shading Language 3.00 Spec](https://www.khronos.org/registry/gles/specs/3.0/GLSL_ES_Specification_3.00.4.pdf)
+
+- [The WebGL Specs](https://www.khronos.org/registry/webgl/specs/latest/)
+
+- [A modern desktop OpenGL Spec](https://www.opengl.org/registry/doc/glspec45.core.pdf)
+  (for reference)
+
+- [The Vulkan Spec](https://www.khronos.org/registry/vulkan/specs/1.0-wsi_extensions/html/vkspec.html)
+
+These specs can be found in the [OpenGL Registry](https://github.com/KhronosGroup/OpenGL-Registry)
+and the [Vulkan Docs](https://github.com/KhronosGroup/Vulkan-Docs) repositories as well.
+
+## Join Groups and Chats
+
+- Join the `#angle` channel in `chromium.slack.com`.
+
+### For Googlers
+
+- Join angle-team@ for access to many important emails and shared documents.
+
+- We have a Hangouts Chat channel. Ask for an invite.

doc/Starter-Projects.md

+# ANGLE Starter Projects
+
+For the most up-to-date list of starter projects, see
+[anglebug.com](https://bugs.chromium.org/p/angleproject/issues/list?q=Hotlist%3DStarterBug).  If you
+decide to take on any task, write a comment so you can get in touch with us, and more importantly,
+set yourself as the "owner" of the bug.  This avoids having multiple people accidentally working on
+the same issue.
+
+## Refactors
+
+### EGL Validation Refactoring
+
+[anglebug.com/798](http://anglebug.com/798)
+
+Move all EGL validation into separate functions in ValidationEGL.h. This opens up many possibilities
+for auto-generation of entry points and is simply a cleaner structure.
+
+### EGL Entry Point Auto-generation
+
+[anglebug.com/2621](http://anglebug.com/2621)
+
+Auto-generate EGL entry points and stub functions. This greatly reduces the chance of bugs in this
+highly repetitive code and reduces the friction to adding new extensions.
+
+### Support Separate Read and Draw Surfaces
+
+[anglebug.com/2620](http://anglebug.com/2620)
+
+ANGLE has never supported binding separate read and draw surfaces with eglMakeCurrent due to its
+architecture. Some refactoring could be done to support this use case.
+
+### Convert GLenums into typed internal Enums
+
+[anglebug.com/2169](http://anglebug.com/2169)
+
+Using a compact enum instead of GLenum offers type safety. Flat enums can also index into flat
+arrays. We are in the process of migrating all internal GLenums into packed enums.
+
+## Medium Features
+
+### Add an AST Validator to the Shader Translator
+
+[anglebug.com/2733](http://anglebug.com/2733)
+
+An AST validator will reduce the number of bugs in our AST transforms and allow us to be more
+confident about all ASTs generated by the translator.
+
+## Small Features
+
+### Fix shader source viewing in RenderDoc/NSIGHT
+
+[anglebug.com/2734](http://anglebug.com/2734)
+
+It used to be possible to view the shader source when debugging shaders in graphics debuggers but
+now only the shader disassembly is available.
+
+### Implement Android CDD Extensions
+
+[anglebug.com/2506](http://anglebug.com/2506)
+
+The Android CDD requires some EGL and OpenGL ES extensions from every driver. Many of them are
+simply exposing the native driver's extension to ANGLE's frontend.
+
+## Performance
+
+### Add perf test for eglMakeCurrent
+
+[anglebug.com/2556](http://anglebug.com/2556)
+
+Many customers switch Contexts frequently. MakeCurrent shows up as a hotspot. A performance test
+would protect against regressions.
+
+### Refactor std::maps into Static Arrays
+
+[anglebug.com/1389](http://anglebug.com/1389)
+
+ANGLE uses internal global maps for texture tables. We should rewrite them to save on binary size
+and optimize startup time.
+
+## Maintenance
+
+### Add a presubmit python script
+
+[anglebug.com/2626](http://anglebug.com/2626)
+
+This simple script could verify that there is no diff on git cl upload.  This saves developer time
+in the long run.
+
+## Conformance
+
+### Vulkan ES2 fixes
+
+[anglebug.com/2615](http://anglebug.com/2615) - see open blocking bugs. Also
+[this link](https://bugs.chromium.org/p/angleproject/issues/list?can=2&q=Renderer%3DVulkan+-has%3Aowner&colspec=ID+Type+Status+Priority+Feature+Owner+Summary&cells=ids)
+for open issues.
+
+Many small edge cases still need attention.
+
+### WebGL Conformance on Windows
+
+[tracking document](https://docs.google.com/spreadsheets/d/1NQePFOdCKT1WKG2P4Qt8igLrLVy4U3vLOLvVWwbkllw/edit?usp=sharing)
+
+ANGLE is preparing to release its OpenGL backend on Windows in Chrome using the passthrough command
+decoder. There are still some failing WebGL tests.
+
+### EGL Conformance
+
+[anglebug.com/2623](http://anglebug.com/2623)
+
+ANGLE's EGL implementation has a lot of holes in it's conformance. There are many tests that fail on
+all platforms due to bugs in ANGLE's EGL frontend.