diff --git a/src/Graphics/CommandBuffer.cs b/src/Graphics/CommandBuffer.cs
index 8b464d8b..33045b3a 100644
--- a/src/Graphics/CommandBuffer.cs
+++ b/src/Graphics/CommandBuffer.cs
@@ -1,10 +1,13 @@
using System;
-using System.Runtime.InteropServices;
using MoonWorks.Math;
using RefreshCS;
namespace MoonWorks.Graphics
{
+ ///
+ /// Command buffers are used to apply render state and issue draw calls.
+ /// NOTE: it is not recommended to hold references to command buffers long term.
+ ///
public class CommandBuffer
{
public GraphicsDevice Device { get; }
@@ -17,6 +20,15 @@ namespace MoonWorks.Graphics
Handle = IntPtr.Zero;
}
+ ///
+ /// Begins a render pass.
+ /// All render state, resource binding, and draw commands must be made within a render pass.
+ /// It is an error to call this after calling BeginRenderPass but before calling EndRenderPass.
+ ///
+ /// The render pass object to begin.
+ /// The framebuffer used by the render pass.
+ /// The screen area of the render pass.
+ /// Clear values for the depth/stencil buffer. This is ignored if the render pass does not clear.
public unsafe void BeginRenderPass(
RenderPass renderPass,
Framebuffer framebuffer,
@@ -35,6 +47,16 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Begins a render pass.
+ /// All render state, resource binding, and draw commands must be made within a render pass.
+ /// It is an error to call this after calling BeginRenderPass but before calling EndRenderPass.
+ ///
+ /// The render pass object to begin.
+ /// The framebuffer used by the render pass.
+ /// The screen area of the render pass.
+ /// Clear values for the depth/stencil buffer. This is ignored if the render pass does not clear.
+ /// Color clear values for each render target in the framebuffer.
public unsafe void BeginRenderPass(
RenderPass renderPass,
Framebuffer framebuffer,
@@ -65,9 +87,17 @@ namespace MoonWorks.Graphics
(uint)clearColors.Length,
depthStencilClearValue.ToRefresh()
);
-
}
+ ///
+ /// Begins a render pass.
+ /// All render state, resource binding, and draw commands must be made within a render pass.
+ /// It is an error to call this after calling BeginRenderPass but before calling EndRenderPass.
+ ///
+ /// The render pass object to begin.
+ /// The framebuffer used by the render pass.
+ /// The screen area of the render pass.
+ /// Color clear values for each render target in the framebuffer.
public unsafe void BeginRenderPass(
RenderPass renderPass,
Framebuffer framebuffer,
@@ -99,6 +129,35 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Begins a render pass.
+ /// All render state, resource binding, and draw commands must be made within a render pass.
+ /// It is an error to call this after calling BeginRenderPass but before calling EndRenderPass.
+ ///
+ /// The render pass object to begin.
+ /// The framebuffer used by the render pass.
+ /// The screen area of the render pass.
+ public unsafe void BeginRenderPass(
+ RenderPass renderPass,
+ Framebuffer framebuffer,
+ in Rect renderArea
+ ) {
+ Refresh.Refresh_BeginRenderPass(
+ Device.Handle,
+ Handle,
+ renderPass.Handle,
+ framebuffer.Handle,
+ renderArea.ToRefresh(),
+ IntPtr.Zero,
+ 0,
+ IntPtr.Zero
+ );
+ }
+
+ ///
+ /// Binds a compute pipeline so that compute work may be dispatched.
+ ///
+ /// The compute pipeline to bind.
public void BindComputePipeline(
ComputePipeline computePipeline
) {
@@ -109,6 +168,10 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Binds buffers to be used in the compute shader.
+ ///
+ /// A set of buffers to bind.
public unsafe void BindComputeBuffers(
params Buffer[] buffers
) {
@@ -126,6 +189,10 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Binds textures to be used in the compute shader.
+ ///
+ /// A set of textures to bind.
public unsafe void BindComputeTextures(
params Texture[] textures
) {
@@ -143,6 +210,10 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Binds a graphics pipeline so that rendering work may be performed.
+ ///
+ /// The graphics pipeline to bind.
public void BindGraphicsPipeline(
GraphicsPipeline graphicsPipeline
) {
@@ -153,6 +224,11 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Binds vertex buffers to be used by subsequent draw calls.
+ ///
+ /// The index of the first buffer to bind.
+ /// Buffers to bind and their associated offsets.
public unsafe void BindVertexBuffers(
uint firstBinding,
params BufferBinding[] bufferBindings
@@ -176,6 +252,10 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Binds vertex buffers to be used by subsequent draw calls.
+ ///
+ /// The buffers to bind.
public unsafe void BindVertexBuffers(
params Buffer[] buffers
) {
@@ -198,6 +278,12 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Binds an index buffer to be used by subsequent draw calls.
+ ///
+ /// The index buffer to bind.
+ /// The size in bytes of the index buffer elements.
+ /// The offset index for the buffer.
public void BindIndexBuffer(
Buffer indexBuffer,
IndexElementSize indexElementSize,
@@ -212,6 +298,11 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Binds samplers to be used by the vertex shader.
+ ///
+ /// An array of texture-sampler pairs to bind.
+ /// The number of texture-sampler pairs from the array to bind.
public unsafe void BindVertexSamplers(
TextureSamplerBinding[] textureSamplerBindings,
int length
@@ -233,12 +324,21 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Binds samplers to be used by the vertex shader.
+ ///
+ /// The texture-sampler pairs to bind.
public unsafe void BindVertexSamplers(
params TextureSamplerBinding[] textureSamplerBindings
) {
BindVertexSamplers(textureSamplerBindings, textureSamplerBindings.Length);
}
+ ///
+ /// Binds samplers to be used by the fragment shader.
+ ///
+ /// An array of texture-sampler pairs to bind.
+ /// The number of texture-sampler pairs from the given array to bind.
public unsafe void BindFragmentSamplers(
TextureSamplerBinding[] textureSamplerBindings,
int length
@@ -260,12 +360,24 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Binds samplers to be used by the fragment shader.
+ ///
+ /// An array of texture-sampler pairs to bind.
public unsafe void BindFragmentSamplers(
params TextureSamplerBinding[] textureSamplerBindings
) {
BindFragmentSamplers(textureSamplerBindings, textureSamplerBindings.Length);
}
+ ///
+ /// Clears the render targets on the current framebuffer to a single color or depth/stencil value.
+ /// NOTE: It is recommended that you clear when beginning render passes unless you have a good reason to clear mid-pass.
+ ///
+ /// The area of the framebuffer to clear.
+ /// Whether to clear colors, depth, or stencil value, or multiple.
+ /// The depth/stencil clear values. Will be ignored if color is not provided in ClearOptions.
+ /// The color clear values. Must provide one per render target. Can be omitted if depth/stencil is not cleared.
public unsafe void Clear(
in Rect clearRect,
ClearOptionsFlags clearOptions,
@@ -295,6 +407,16 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Draws using instanced rendering.
+ /// It is an error to call this method unless two vertex buffers have been bound.
+ ///
+ /// The starting index offset for the vertex buffer.
+ /// The starting index offset for the index buffer.
+ /// The number of primitives to draw.
+ /// The number of instances to draw.
+ /// An offset value obtained from PushVertexShaderUniforms. If no uniforms are required then use 0.
+ /// An offset value obtained from PushFragmentShaderUniforms. If no uniforms are required the use 0.
public void DrawInstancedPrimitives(
uint baseVertex,
uint startIndex,
@@ -315,6 +437,14 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Draws using a vertex buffer and an index buffer.
+ ///
+ /// The starting index offset for the vertex buffer.
+ /// The starting index offset for the index buffer.
+ /// The number of primitives to draw.
+ /// An offset value obtained from PushVertexShaderUniforms. If no uniforms are required then use 0.
+ /// An offset value obtained from PushFragmentShaderUniforms. If no uniforms are required the use 0.
public void DrawIndexedPrimitives(
uint baseVertex,
uint startIndex,
@@ -333,6 +463,13 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Draws using a vertex buffer.
+ ///
+ ///
+ ///
+ ///
+ ///
public void DrawPrimitives(
uint vertexStart,
uint primitiveCount,
@@ -349,6 +486,10 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Ends the current render pass.
+ /// This must be called before beginning another render pass or submitting the command buffer.
+ ///
public void EndRenderPass()
{
Refresh.Refresh_EndRenderPass(
@@ -357,12 +498,17 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Prepares a texture to be presented to the screen.
+ ///
+ /// The texture to present.
+ /// The area of the screen to present to.
+ /// The filter to use when the texture size differs from the destination rectangle.
public void QueuePresent(
in Texture texture,
in Rect destinationRectangle,
Filter filter
- )
- {
+ ) {
var refreshRect = destinationRectangle.ToRefresh();
var refreshTextureSlice = new Refresh.TextureSlice
{
@@ -388,6 +534,12 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Prepares a texture slice to be presented to the screen.
+ ///
+ /// The texture slice to present.
+ /// The area of the screen to present to.
+ /// The filter to use when the texture size differs from the destination rectangle.
public void QueuePresent(
in TextureSlice textureSlice,
in Rect destinationRectangle,
@@ -405,6 +557,12 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Prepares a texture slice to be presented to the screen.
+ /// This particular variant of this method will present to the entire window area.
+ ///
+ /// The texture slice to present.
+ /// The filter to use when the texture size differs from the window size.
public void QueuePresent(
in TextureSlice textureSlice,
Filter filter
@@ -418,6 +576,12 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Prepares a texture to be presented to the screen.
+ /// This particular variant of this method will present to the entire window area.
+ ///
+ /// The texture to present.
+ /// The filter to use when the texture size differs from the window size.
public void QueuePresent(
Texture texture,
Filter filter
@@ -446,6 +610,12 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Performs an asynchronous texture-to-texture copy on the GPU.
+ ///
+ /// The texture slice to copy from.
+ /// The texture slice to copy to.
+ /// The filter to use if the sizes of the texture slices differ.
public void CopyTextureToTexture(
in TextureSlice sourceTextureSlice,
in TextureSlice destinationTextureSlice,
@@ -463,6 +633,12 @@ namespace MoonWorks.Graphics
);
}
+ ///
+ /// Performs an asynchronous texture-to-buffer copy.
+ /// Note that the buffer is not guaranteed to be filled until you call GraphicsDevice.Wait()
+ ///
+ ///
+ ///
public void CopyTextureToBuffer(
in TextureSlice textureSlice,
Buffer buffer