diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d18890bef..44bcd866c 100644 --- a/CONTRIBUTING.md +++ b/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 -kept clean. If not, you will be asked to rebase them (and if you don't know what -that means, avoid getting into that situation ;). +best and multiple commits in a pull request are allowed only if they are +kept clean. If not clean, you will be asked to rebase your pulls (and if +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. diff --git a/README.md b/README.md index f9a6e8e32..f5cc41ceb 100644 --- a/README.md +++ b/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 -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 +Come chat with us about **emulator-related 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: -[![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. +Some real games run. Most don't. 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 - > cd xenia - > xb setup +> git clone https://github.com/benvanik/xenia.git +> cd xenia +> xb setup - # Pull latest changes, rebase, and update submodules and premake: - > xb pull +# Pull latest changes, rebase, and update submodules and premake: +> xb pull - # Build on command line: - > xb build +# Build on command line: +> xb build - # Run premake and open Visual Studio (run the 'xenia-app' project): - > xb devenv +# Run premake and open Visual Studio (run the 'xenia-app' project): +> xb devenv - # Run premake to update the sln/vcproj's: - > xb premake +# Run premake to update the sln/vcproj's: +> xb premake - # Format code to the style guide: - > xb format +# Format code to the style guide: +> 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. \ No newline at end of file diff --git a/docs/gpu.md b/docs/gpu.md index 97a0fa8fe..d2e8eafba 100644 --- a/docs/gpu.md +++ b/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`.