From 72c676a1e00e54614373fd64d7f37077822c3613 Mon Sep 17 00:00:00 2001 From: cosmonaut Date: Tue, 23 Feb 2021 23:41:14 -0800 Subject: [PATCH] add doc comments to CommandBuffer --- src/Graphics/CommandBuffer.cs | 184 +++++++++++++++++++++++++++++++++- 1 file changed, 180 insertions(+), 4 deletions(-) diff --git a/src/Graphics/CommandBuffer.cs b/src/Graphics/CommandBuffer.cs index 8b464d8..33045b3 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