graphics device stuff

content/Game/_index.md

@@ -42,7 +42,7 @@ namespace MyProject
 
 `PresentMode` refers to the way that your game's render is presented to the screen. The differences and trade-offs boil down to visible tearing vs latency.
 
-The two modes that allow tearing are Immediate and FIFORelaxed.
+The two modes that allow tearing are `Immediate` and `FIFORelaxed`.
 
 `Immediate` means that the presentation system does not wait for vertical refresh to update the screen and presents the image as soon as possible.
 
@@ -66,6 +66,6 @@ MoonWorks automatically updates input and audio state before calling your game's
 
 Rendering code goes here. I recommend structuring your codebase so that your Game class doesn't just become a big mess of graphics resources.
 
-You might be wondering what `alpha` refers to. What if you set your game to update at 60 frames per second but one of your users has, for example, a 144Hz monitor? This will result in ugly stuttering as the game logic and monitor update out-of-step with each other. `alpha` gets filled in with a value between 0 and 1 which refers to a blending factor between the previous game state and current game state. This will allow you to linearly interpolate your position and rotation values between the two states to eliminate this stuttering.
+You might be wondering what `alpha` refers to. What if you set your game to update at 60 frames per second but one of your users has, for example, a 144Hz monitor? This will result in ugly stuttering as the game logic and rendering update out-of-step with each other. `alpha` gets filled in with a value between 0 and 1 which refers to a blending factor between the previous game state and current game state. This will allow you to linearly interpolate your position and rotation values between the two states to eliminate this stuttering.
 
 For a more in-depth explanation of this behavior, I recommend reading the [Fix Your Timestep](https://www.gafferongames.com/post/fix_your_timestep/) article.

content/Graphics/GraphicsDevice.md

@@ -3,3 +3,66 @@ title: "Graphics Device"
 date: 2021-01-24T20:52:59-08:00
 ---
 
+`GraphicsDevice` is your main entry point for graphics-related behavior. You can obtain a reference to the current `GraphicsDevice` from your `Game` class.
+
+Rendering in MoonWorks.Graphics is mostly handled through an abstraction known as the command buffer.
+You will acquire a command buffer from the `GraphicsDevice`, tell it to do things, and then submit it to the GraphicsDevice for processing.
+
+```cs
+var commandBuffer = GraphicsDevice.AcquireCommandBuffer();
+
+// do things with command buffer
+
+GraphicsDevice.Submit(commandBuffer);
+```
+
+You will also need to provide the GraphicsDevice to load graphics resources. For example:
+
+```cs
+var myTexture = Texture.LoadPNG(GraphicsDevice, "grass.png");
+```
+
+There is one last thing that the GraphicsDevice can do, and that is `Wait`. To understand waiting, you need to understand a little bit about how MoonWorks.Graphics processes rendering.
+
+Rendering is asynchronous. This means that when you submit a command buffer, the program doesn't actually wait for the GPU to finish working on whatever commands you submitted. It just tells the GPU what to do and then keeps going with your program. This is very powerful.
+
+Sometimes you actually do want to wait for the GPU to be done with the work you asked it to do, like if you are grabbing a screenshot for example. This is where `Wait` comes in.
+
+```cs
+// in initializer
+screenshotThread = new Thread(new ThreadStart(SaveScreenshot));
+
+...
+
+protected void Draw(double dt, double alpha)
+{
+    // do other rendering stuff
+
+    if (screenshotActivated)
+    {
+        commandBuffer.CopyTextureToBuffer(myTextureSlice, screenshotBuffer);
+    }
+
+    GraphicsDevice.Submit(commandBuffer);
+
+    if (screenshotActivated)
+    {
+        screenshotThread.Start();
+    }
+}
+
+...
+
+private void SaveScreenshot9)
+{
+    GraphicsDevice.Wait();
+    screenshotBuffer.GetData(screenshotPixels, screenShotBufferSize);
+    Texture.SavePNG("screenshot.png", 1280, 720, screenshotPixels);
+}
+```
+
+In this example, a separate CPU thread waits for the GPU to be done working. Then it saves some pixels that the GPU moved into a buffer to the disk as a PNG. Note that this means the game doesn't stutter at all while the disk is written to, because a separate thread from the main execution thread handles saving to disk.
+
+If you need to squeeze some performance out of your game or avoid a lengthy stutter while the disk is accessed, threading can go a long way.
+
+Before we talk too much more about command buffers and threading, let's explain the different kinds of graphics resources that you need for rendering.

content/_index.md

@@ -15,4 +15,6 @@ MoonWorks **does not** include things like a built-in physics engine, a GUI edit
 
 MoonWorks uses strictly Free Open Source Software. It does not have any kind of dependency on proprietary products, and it never will! I have been working professionally on games for nearly a decade and in that time I have learned that proprietary software is utterly disastrous for long-term maintenance of projects. You deserve to have the freedom to own your development process.
 
+This document is intended as a guide for getting your head around how to use MoonWorks in practice. For the actual API reference, the source is documented extensively in doc comments that your preferred IDE can read.
+
 If all this sounds good to you, read on!