From cb61b849feaa757c83a5b0988624228607a623a0 Mon Sep 17 00:00:00 2001 From: cosmonaut Date: Thu, 13 Jan 2022 12:32:42 -0800 Subject: [PATCH] update docs with ABI changes --- content/Graphics/CommandBuffer/_index.md | 35 +++++++++++++++++-- content/Graphics/Resources/ComputePipeline.md | 6 ---- .../GraphicsPipeline/GraphicsPipeline.md | 7 ---- content/Graphics/Resources/Texture.md | 13 ++++--- 4 files changed, 40 insertions(+), 21 deletions(-) diff --git a/content/Graphics/CommandBuffer/_index.md b/content/Graphics/CommandBuffer/_index.md index e6a8a1e..08b6b96 100644 --- a/content/Graphics/CommandBuffer/_index.md +++ b/content/Graphics/CommandBuffer/_index.md @@ -77,6 +77,17 @@ myCommandBuffer.BindFragmentSamplers( Note that you may provide one or more samplers to a shader, and the samplers you provide will be indexed by the shader in the order they are provided to the function. +## Pushing Uniforms + +If your shader stages take uniforms, you can push them after binding a pipeline. + +```cs +var myVertUniformOffset = myCommandBuffer.PushVertexShaderUniforms(myVertUniforms); +var myFragUniformOffset = myCommandBuffer.PushFragmentShaderUniforms(myFragUniforms); +``` + +The offsets you receive from these functions should be passed to draw calls. You can push these one at a time, but if you want to be clever, you can upload multiple uniform buffers at once and then manually increment your offsets at the appropriate draw calls. + ## Drawing Primitives Now that we've set up all this render state, we can start issuing draw calls. @@ -84,7 +95,12 @@ Now that we've set up all this render state, we can start issuing draw calls. To draw using a single vertex buffer and no index buffer, call `DrawPrimitives`. You must provide a starting vertex, a primitive count, and offset values for each shader stage. (If you do not provide uniforms for a particular stage, just use `0`.) ```cs -myCommandBuffer.DrawPrimitives(0, myTriangleCount, myVertexUniformOffset, myFragmentUniformOffset); +myCommandBuffer.DrawPrimitives( + 0, + myTriangleCount, + myVertexUniformOffset, + myFragmentUniformOffset +); ``` Note that the existence of the uniform offset pattern enables you to loop over a bunch of draw calls and update the uniforms without having to push uniforms every loop. Remember that you can greatly increase your performance by packing as much data into a single vertex buffer as possible. @@ -92,13 +108,26 @@ Note that the existence of the uniform offset pattern enables you to loop over a To draw using a single vertex buffer and an index buffer, call `DrawIndexedPrimitives`. You must provide a starting vertex, a starting index, a primitive count, and offset values for each shader stage. ```cs -myCommandBuffer.DrawIndexedPrimitives(0, 0, myTriangleCount, myVertexUniformOffset, myFragmentUniformOffset); +myCommandBuffer.DrawIndexedPrimitives( + 0, + 0, + myTriangleCount, + myVertexUniformOffset, + myFragmentUniformOffset +); ``` To draw using multiple vertex buffers and an index buffer, call `DrawInstancedPrimitives`. You must provide a starting vertex, a starting index, a primitive count, an instance count, and offset values for each shader stage. ```cs -myCommandBuffer.DrawInstancedPrimitives(0, 0, myTriangleCount, myInstanceCount, myVertexUniformOffset, myFragmentUniformOffset); +myCommandBuffer.DrawInstancedPrimitives( + 0, + 0, + myTriangleCount, + myInstanceCount, + myVertexUniformOffset, + myFragmentUniformOffset +); ``` ## Ending the Render Pass diff --git a/content/Graphics/Resources/ComputePipeline.md b/content/Graphics/Resources/ComputePipeline.md index a14c336..e2f5318 100644 --- a/content/Graphics/Resources/ComputePipeline.md +++ b/content/Graphics/Resources/ComputePipeline.md @@ -32,9 +32,3 @@ var myComputePipeline = new ComputePipeline( ``` This example creates a compute pipeline with no uniform input, one buffer binding, and no image bindings. - -Similar to graphics pipelines, uniforms can also be pushed to compute pipelines. - -```cs -var myComputeUniformOffset = myComputePipeline.PushComputeShaderUniforms(myComputeUniforms); -``` diff --git a/content/Graphics/Resources/GraphicsPipeline/GraphicsPipeline.md b/content/Graphics/Resources/GraphicsPipeline/GraphicsPipeline.md index a46c45e..d597053 100644 --- a/content/Graphics/Resources/GraphicsPipeline/GraphicsPipeline.md +++ b/content/Graphics/Resources/GraphicsPipeline/GraphicsPipeline.md @@ -29,10 +29,3 @@ var myGraphicsPipeline = new GraphicsPipeline( ``` Finally! That's it! You might have noticed that a lot of this structure can be reused across pipelines. I strongly recommend creating individual container objects for the various states your renderer uses so you don't have to repeat yourself a whole bunch. - -Graphics pipelines are unique from our other resources so far because they have two methods that are used to push uniforms. These methods return offset values that are used with draw commands. - -```cs -var vertUniformOffset = myGraphicsPipeline.PushVertexShaderUniforms(myVertUniforms); -var fragUniformOffset = myGraphicsPipeline.PushFragmentShaderUniforms(myFragUniforms); -``` diff --git a/content/Graphics/Resources/Texture.md b/content/Graphics/Resources/Texture.md index 7c8f036..11f2f59 100644 --- a/content/Graphics/Resources/Texture.md +++ b/content/Graphics/Resources/Texture.md @@ -27,15 +27,18 @@ var myTexture = new Texture(GraphicsDevice, textureCreateInfo); This sets up 128x128 2D Texture that uses 32 bits per pixel: 8 bits each for red, green, blue, and alpha. We also indicate that we intend to use the texture for sampling. -To put pixels in the texture, we use the `SetData` method. +To put pixels in the texture, we use the `SetTextureData` method on a command buffer. ```cs var pixels = new Color[width * height]; -// set pixel array data here -myTexture.SetData(pixels); +// put data in the pixel array here! + +myCommandBuffer.SetTextureData(myTexture, pixels); ``` +We'll get to command buffers later, just know that you must upload data via command buffer so that you safely use multithreading. This can speed up load times greatly. + Of course, having to fill in all this data every time is kind of cumbersome, so we have some shortcut methods for common texture usages. ```cs @@ -47,7 +50,7 @@ var myCubeTexture = Texture.CreateTextureCube(GraphicsDevice, 128, TextureFormat There is also a built-in PNG loader that creates a 2D R8G8B8A8 texture and fills it with pixel data. ```cs -var myPNGTexture = Texture.LoadPNG(GraphicsDevice, "coldsteel_the_hedgehog.png"); +var myPNGTexture = Texture.LoadPNG(GraphicsDevice, myCommandBuffer, "coldsteel_the_hedgehog.png"); ``` One last concept we should discuss before moving on is texture slicing. @@ -55,7 +58,7 @@ One last concept we should discuss before moving on is texture slicing. Texture slices are a very commonly used concept in MoonWorks. You don't have to do texture operations on an entire texture - you can instead use a subsection of the texture for whatever your operation is. ```cs -var myTexture = Texture.Load(GraphicsDevice, "myTexture.png"); +var myTexture = Texture.LoadPNG(GraphicsDevice, "myTexture.png"); var mySliceRect = new Rect(0, 0, 16, 16); var myTextureSlice = new TextureSlice(myTexture, mySliceRect); ```