Updating some documentation.

CONTRIBUTING.md

@@ -41,9 +41,9 @@ identify regressions. Such tools require a clean git history to function
 properly. Incoming pull requests must follow good git rules, the most basic of
 which is that individual commits add functionality in somewhat working form and
 fully compile and run on their own. Small pull requests with a single commit are
-best, however multiple commits in a pull request are allowed only if they are
+best and multiple commits in a pull request are allowed only if they are
-kept clean. If not, you will be asked to rebase them (and if you don't know what
+kept clean. If not clean, you will be asked to rebase your pulls (and if
-that means, avoid getting into that situation ;).
+you don't know what that means, avoid getting into that situation ;).
 
 Example of a bad commit history:
 
@@ -75,4 +75,4 @@ change to a fundamentally incompatible license.
 Any `third_party/` code added will be reviewed for conformance with the license.
 In general, GPL code is forbidden unless it is used exclusively for
 development-time tooling (like compiling). LGPL code is strongly discouraged as
-it complicates building. Unless extremely trivial (such as )
+it complicates building.

README.md

@@ -4,32 +4,22 @@ Xenia - Xbox 360 Emulator Research Project
 Xenia is an experimental emulator for the Xbox 360. For more information see the
 [main xenia website](http://xenia.jp/).
 
-Pull requests are welcome but the code is in a very high churn state and may not
+Come chat with us about **emulator-related topics in
-be accepted, so ask in IRC before taking on anything big. Contributions are
-awesome but the focus of the developers is on writing new code, not teaching
-programming or answering questions. If you'd like to casually help out it may
-be better to wait a bit until things calm down and more of the code is documented.
-
-Come chat with us **about development topics** in
 [#xenia @ irc.freenode.net](http://webchat.freenode.net?channels=%23xenia&uio=MTE9NzIaa).
+For developer chat join `#xenia-dev` but stay on topic. Lurking is fine.
 Please check the [frequently asked questions](http://xenia.jp/faq/) page before
 asking questions. We've got jobs/lives/etc, so don't expect instant answers.
 Discussing illegal activities will get you banned. No warnings.
 
-**Before contributing code or issues be sure to read [CONTRIBUTING.md](CONTRIBUTING.md).**
-
 ## Status
 
 Buildbot:
 [![Build status](http://build.xenia.jp/png?builder=auto-builds)](http://build.xenia.jp/waterfall)
 
-Project tracker:
+Some real games run. Most don't.
-[![Stories in Ready](https://badge.waffle.io/benvanik/xenia.svg?label=ready&title=Ready)](http://waffle.io/benvanik/xenia)
-[![Stories in In Progress](https://badge.waffle.io/benvanik/xenia.svg?label=in%20progress&title=In%20Progress)](http://waffle.io/benvanik/xenia)
-
-Some real games run. Most don't. Don't ask if GTA or whatever runs.
 See the [Game compatibility list](https://github.com/xenia-project/game-compatibility/issues)
-for currently tracked games.
+for currently tracked games and feel free to contribute your own updates,
+screenshots, and information there following the [existing conventions](https://github.com/xenia-project/game-compatibility/blob/master/README.md).
 
 ## Disclaimer
 
@@ -43,24 +33,24 @@ legally purchased devices and games and information made public on the internet
 
 Windows 8.1+ with Python 2.7 and [Visual Studio 2015](https://www.visualstudio.com/downloads/download-visual-studio-vs) and the Windows SDKs installed:
 
-    > git clone https://github.com/benvanik/xenia.git
+> git clone https://github.com/benvanik/xenia.git
-    > cd xenia
+> cd xenia
-    > xb setup
+> xb setup
 
-    # Pull latest changes, rebase, and update submodules and premake:
+# Pull latest changes, rebase, and update submodules and premake:
-    > xb pull
+> xb pull
 
-    # Build on command line:
+# Build on command line:
-    > xb build
+> xb build
 
-    # Run premake and open Visual Studio (run the 'xenia-app' project):
+# Run premake and open Visual Studio (run the 'xenia-app' project):
-    > xb devenv
+> xb devenv
 
-    # Run premake to update the sln/vcproj's:
+# Run premake to update the sln/vcproj's:
-    > xb premake
+> xb premake
 
-    # Format code to the style guide:
+# Format code to the style guide:
-    > xb format
+> xb format
 
 When fetching updates use `xb pull` to automatically fetch everything and
 run premake for project files/etc.
@@ -73,6 +63,8 @@ and be sure to run clang-format!
 
 ## Contributors Wanted!
 
+**Before contributing code or issues be sure to read [CONTRIBUTING.md](CONTRIBUTING.md).**
+
 Have some spare time, know advanced C++, and want to write an emulator?
 Contribute! There's a ton of work that needs to be done, a lot of which
 is wide open greenfield fun.
@@ -95,4 +87,4 @@ For more see the main [frequently asked questions](http://xenia.jp/faq/) page.
 
 ### Can I get an exe?
 
-Not yet.
+Not yet.

docs/gpu.md

@@ -17,10 +17,49 @@ Buggy GL implementations can benefit from `--thread_safe_gl`.
 
 ## Tools
 
-### Shader Dumps
+### Shaders
+
+#### Shader Dumps
 
 Adding `--dump_shaders=path/` will write all translated shaders to the given
 path with names based on input hash (so they'll be stable across runs).
+Binaries containing the original microcode will be placed side-by-side with
+the dumped output to make it easy to pipe to `xe-gpu-shader-compiler`.
+
+#### xe-gpu-shader-compiler
+
+A standalone shader compiler exists to allow for quick shader translation
+testing. You can pass a binary ucode shader in and get either disassembled
+ucode or translated source out. This is best used through the Shader
+Playground tool.
+
+```
+  xe-gpu-shader-compiler \
+      --shader_input=input_file.bin.vs (or .fs)
+      --shader_output=output_file.txt
+      --shader_output_type=ucode (or spirvtext)
+```
+
+#### Shader Playground
+
+Built separately (for now) under [tools/shader-playground/](https://github.com/benvanik/xenia/blob/master/tools/shader-playground/)
+is a GUI for interactive shader assembly, disassembly, validation, and
+translation.
+
+TODO(benvanik): screen shot.
+
+Entering shader microcode on the left will invoke the XNA Game Studio
+D3D compiler to translate the ucode to binary. The D3D compiler is then
+used to disassemble the binary and display the optimized form. If
+`xe-gpu-shader-compiler` has been built the ucode will be passed to that
+for disassembly and that will then be passed through D3D compiler. If
+the output of D3D compiler on the xenia disassembly doesn't match the
+original D3D compiler output the box will turn red, indicating that the
+disassembly is broken. Finally, the right most box will show the
+translated shader in the desired format.
+
+For more information and setup instructions see
+[tools/shader-playground/README.md](https://github.com/benvanik/xenia/blob/master/tools/shader-playground/README.md).
 
 ### xe-gpu-trace-viewer
 
@@ -61,11 +100,3 @@ you to seek through them in the trace viewer. These files will get large.
 * [LLVM R600 Tables](https://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Target/R600/R600Instructions.td)
 ** The opcode formats don't match, but the name->psuedo code is correct.
 * [xemit](https://github.com/gligli/libxemit/blob/master/xemitops.c)
-
-## Tools
-
-### apitrace
-
-[apitrace](http://apitrace.github.io/) can be used to capture and replay D3D11
-call streams. To disable stdout spew first set `XE_OPTION_ENABLE_LOGGING` to 0
-in `logging.h`.