diff --git a/src/Graphics/RefreshEnums.cs b/src/Graphics/RefreshEnums.cs index fb26909a..4cb9ffba 100644 --- a/src/Graphics/RefreshEnums.cs +++ b/src/Graphics/RefreshEnums.cs @@ -22,6 +22,9 @@ namespace MoonWorks.Graphics TriangleStrip } + /// + /// Describes the operation that a render pass will use when loading a render target. + /// public enum LoadOp { Load, @@ -29,6 +32,9 @@ namespace MoonWorks.Graphics DontCare } + /// + /// Describes the operation that a render pass will use when storing a render target. + /// public enum StoreOp { Store, diff --git a/src/Graphics/Resources/Buffer.cs b/src/Graphics/Resources/Buffer.cs index 0f3900da..8004064c 100644 --- a/src/Graphics/Resources/Buffer.cs +++ b/src/Graphics/Resources/Buffer.cs @@ -4,10 +4,19 @@ using RefreshCS; namespace MoonWorks.Graphics { + /// + /// Buffers are generic data containers that can be used by the GPU. + /// public class Buffer : GraphicsResource { protected override Action QueueDestroyFunction => Refresh.Refresh_QueueDestroyBuffer; + /// + /// Creates a buffer. + /// + /// An initialized GraphicsDevice. + /// Specifies how the buffer will be used. + /// The length of the array. Cannot be resized. public Buffer( GraphicsDevice device, BufferUsageFlags usageFlags, @@ -21,6 +30,12 @@ namespace MoonWorks.Graphics ); } + /// + /// Asynchronously copies data into the buffer. + /// + /// An array of data to copy into the buffer. + /// Specifies where to start copying out of the array. + /// Specifies how many elements to copy. public unsafe void SetData( T[] data, uint offsetInElements, @@ -41,6 +56,11 @@ namespace MoonWorks.Graphics } } + /// + /// Asynchronously copies data into the buffer. + /// This variant of this method copies the entire array. + /// + /// An array of data to copy. public unsafe void SetData( T[] data ) where T : unmanaged @@ -57,6 +77,12 @@ namespace MoonWorks.Graphics } } + /// + /// Asynchronously copies data into the buffer. + /// + /// A pointer to an array. + /// Specifies where to start copying the data, in bytes. + /// Specifies how many bytes of data to copy. public void SetData( IntPtr data, uint offsetInBytes, @@ -71,6 +97,12 @@ namespace MoonWorks.Graphics ); } + /// + /// Asynchronously copies data into the buffer. + /// + /// A pointer to an array. + /// Specifies where to start copying the data, in bytes. + /// Specifies how many bytes of data to copy. public unsafe void SetData( T* data, uint offsetInElements, @@ -86,7 +118,12 @@ namespace MoonWorks.Graphics ); } - // NOTE: You want to wait on the device before calling this + /// + /// Reads data out of a buffer and into an array. + /// This operation is only guaranteed to read up-to-date data if GraphicsDevice.Wait is called first. + /// + /// The array that data will be copied to. + /// The length of the data to read. public unsafe void GetData( T[] data, uint dataLengthInBytes diff --git a/src/Graphics/Resources/Framebuffer.cs b/src/Graphics/Resources/Framebuffer.cs index 4be408b7..2ed1cf20 100644 --- a/src/Graphics/Resources/Framebuffer.cs +++ b/src/Graphics/Resources/Framebuffer.cs @@ -4,6 +4,9 @@ using RefreshCS; namespace MoonWorks.Graphics { + /// + /// A framebuffer is a collection of render targets that is rendered to during a render pass. + /// public class Framebuffer : GraphicsResource { protected override Action QueueDestroyFunction => Refresh.Refresh_QueueDestroyFramebuffer; @@ -15,12 +18,21 @@ namespace MoonWorks.Graphics public RenderPass RenderPass { get; } + /// + /// Creates a framebuffer. + /// + /// An initialized GraphicsDevice. + /// The width of the framebuffer. + /// The height of the framebuffer. + /// The reference render pass for the framebuffer. + /// The depth stencil target. Can be null. + /// Anywhere from 0-4 color targets can be provided. public unsafe Framebuffer( GraphicsDevice device, uint width, uint height, RenderPass renderPass, - RenderTarget depthStencilTarget, /* can be NULL */ + RenderTarget depthStencilTarget, params RenderTarget[] colorTargets ) : base(device) { diff --git a/src/Graphics/Resources/GraphicsPipeline.cs b/src/Graphics/Resources/GraphicsPipeline.cs index 863244df..d0310b76 100644 --- a/src/Graphics/Resources/GraphicsPipeline.cs +++ b/src/Graphics/Resources/GraphicsPipeline.cs @@ -4,6 +4,10 @@ using RefreshCS; namespace MoonWorks.Graphics { + /// + /// Graphics pipelines encapsulate all of the render state in a single object. + /// These pipelines are bound before draw calls are issued. + /// public class GraphicsPipeline : GraphicsResource { protected override Action QueueDestroyFunction => Refresh.Refresh_QueueDestroyGraphicsPipeline; diff --git a/src/Graphics/Resources/RenderPass.cs b/src/Graphics/Resources/RenderPass.cs index 81b6acbf..fc5e142a 100644 --- a/src/Graphics/Resources/RenderPass.cs +++ b/src/Graphics/Resources/RenderPass.cs @@ -3,10 +3,18 @@ using RefreshCS; namespace MoonWorks.Graphics { + /// + /// A render pass describes the kind of render targets that will be used in rendering. + /// public class RenderPass : GraphicsResource { protected override Action QueueDestroyFunction => Refresh.Refresh_QueueDestroyRenderPass; + /// + /// Creates a render pass using color target descriptions. + /// + /// An initialized GraphicsDevice. + /// Up to 4 color target descriptions may be provided. public unsafe RenderPass( GraphicsDevice device, params ColorTargetDescription[] colorTargetDescriptions @@ -23,6 +31,12 @@ namespace MoonWorks.Graphics } } + /// + /// Creates a render pass using a depth/stencil target description and optional color target descriptions. + /// + /// An initialized GraphicsDevice. + /// A depth/stencil target description. + /// Up to 4 color target descriptions may be provided. public unsafe RenderPass( GraphicsDevice device, in DepthStencilTargetDescription depthStencilTargetDescription, diff --git a/src/Graphics/Resources/RenderTarget.cs b/src/Graphics/Resources/RenderTarget.cs index 597fa7a0..6a0c3490 100644 --- a/src/Graphics/Resources/RenderTarget.cs +++ b/src/Graphics/Resources/RenderTarget.cs @@ -3,6 +3,9 @@ using RefreshCS; namespace MoonWorks.Graphics { + /// + /// A render target is a structure that wraps a texture so that it can be rendered to. + /// public class RenderTarget : GraphicsResource { public TextureSlice TextureSlice { get; } @@ -10,6 +13,17 @@ namespace MoonWorks.Graphics protected override Action QueueDestroyFunction => Refresh.Refresh_QueueDestroyRenderTarget; + /// + /// Creates a render target backed by a texture. + /// + /// An initialized GraphicsDevice. + /// The width of the render target. + /// The height of the render target. + /// The format of the render target. + /// Whether the render target can be used by a sampler. + /// The multisample count of the render target. + /// The mip level of the render target. + /// public static RenderTarget CreateBackedRenderTarget( GraphicsDevice device, uint width, @@ -52,7 +66,17 @@ namespace MoonWorks.Graphics return new RenderTarget(device, new TextureSlice(texture), sampleCount); } - public RenderTarget(GraphicsDevice device, in TextureSlice textureSlice, SampleCount sampleCount = SampleCount.One) : base(device) + /// + /// Creates a render target using a texture slice and an optional sample count. + /// + /// An initialized GraphicsDevice. + /// The texture slice that will be rendered to. + /// The desired multisample count of the render target. + public RenderTarget( + GraphicsDevice device, + in TextureSlice textureSlice, + SampleCount sampleCount = SampleCount.One + ) : base(device) { Handle = Refresh.Refresh_CreateRenderTarget( device.Handle, diff --git a/src/Graphics/Resources/Sampler.cs b/src/Graphics/Resources/Sampler.cs index 7a99bd3d..e313f691 100644 --- a/src/Graphics/Resources/Sampler.cs +++ b/src/Graphics/Resources/Sampler.cs @@ -3,6 +3,9 @@ using RefreshCS; namespace MoonWorks.Graphics { + /// + /// A sampler specifies how a texture will be sampled in a shader. + /// public class Sampler : GraphicsResource { protected override Action QueueDestroyFunction => Refresh.Refresh_QueueDestroySampler; diff --git a/src/Graphics/Resources/ShaderModule.cs b/src/Graphics/Resources/ShaderModule.cs index 255b147f..63c7eaf1 100644 --- a/src/Graphics/Resources/ShaderModule.cs +++ b/src/Graphics/Resources/ShaderModule.cs @@ -1,9 +1,11 @@ using RefreshCS; using System; -using System.IO; namespace MoonWorks.Graphics { + /// + /// Shader modules expect input in SPIR-V bytecode format. + /// public class ShaderModule : GraphicsResource { protected override Action QueueDestroyFunction => Refresh.Refresh_QueueDestroyShaderModule; diff --git a/src/Graphics/Resources/Texture.cs b/src/Graphics/Resources/Texture.cs index 9e3d3998..6c0009a5 100644 --- a/src/Graphics/Resources/Texture.cs +++ b/src/Graphics/Resources/Texture.cs @@ -5,6 +5,9 @@ using RefreshCS; namespace MoonWorks.Graphics { + /// + /// A container for pixel data. + /// public class Texture : GraphicsResource { public uint Width { get; } @@ -48,6 +51,16 @@ namespace MoonWorks.Graphics } } + /// + /// Creates a 2D texture. + /// + /// An initialized GraphicsDevice. + /// The width of the texture. + /// The height of the texture. + /// The format of the texture. + /// Specifies how the texture will be used. + /// Specifies the multisample count. + /// Specifies the number of mip levels. public static Texture CreateTexture2D( GraphicsDevice device, uint width, @@ -56,8 +69,7 @@ namespace MoonWorks.Graphics TextureUsageFlags usageFlags, SampleCount sampleCount = SampleCount.One, uint levelCount = 1 - ) - { + ) { var textureCreateInfo = new TextureCreateInfo { Width = width, @@ -73,6 +85,17 @@ namespace MoonWorks.Graphics return new Texture(device, textureCreateInfo); } + /// + /// Creates a 3D texture. + /// + /// An initialized GraphicsDevice. + /// The width of the texture. + /// The height of the texture. + /// The depth of the texture. + /// The format of the texture. + /// Specifies how the texture will be used. + /// Specifies the multisample count. + /// Specifies the number of mip levels. public static Texture CreateTexture3D( GraphicsDevice device, uint width, @@ -82,8 +105,7 @@ namespace MoonWorks.Graphics TextureUsageFlags usageFlags, SampleCount sampleCount = SampleCount.One, uint levelCount = 1 - ) - { + ) { var textureCreateInfo = new TextureCreateInfo { Width = width, @@ -99,6 +121,15 @@ namespace MoonWorks.Graphics return new Texture(device, textureCreateInfo); } + /// + /// Creates a cube texture. + /// + /// An initialized GraphicsDevice. + /// The length of one side of the cube. + /// The format of the texture. + /// Specifies how the texture will be used. + /// Specifies the multisample count. + /// Specifies the number of mip levels. public static Texture CreateTextureCube( GraphicsDevice device, uint size, @@ -106,8 +137,7 @@ namespace MoonWorks.Graphics TextureUsageFlags usageFlags, SampleCount sampleCount = SampleCount.One, uint levelCount = 1 - ) - { + ) { var textureCreateInfo = new TextureCreateInfo { Width = size, @@ -123,6 +153,11 @@ namespace MoonWorks.Graphics return new Texture(device, textureCreateInfo); } + /// + /// Creates a new texture using a TextureCreateInfo struct. + /// + /// An initialized GraphicsDevice. + /// The parameters to use when creating the texture. public Texture( GraphicsDevice device, in TextureCreateInfo textureCreateInfo @@ -138,21 +173,38 @@ namespace MoonWorks.Graphics Height = textureCreateInfo.Height; } - public void SetData(in TextureSlice textureSlice, IntPtr data, uint dataLengthInBytes) + /// + /// Asynchronously copies data into the texture. + /// + /// The texture slice to copy into. + /// A pointer to an array of data to copy from. + /// The amount of data to copy from the array. + public void SetData(in TextureSlice textureSlice, IntPtr dataPtr, uint dataLengthInBytes) { Refresh.Refresh_SetTextureData( Device.Handle, textureSlice.ToRefreshTextureSlice(), - data, + dataPtr, dataLengthInBytes ); } - public void SetData(IntPtr data, uint dataLengthInBytes) + /// + /// Asynchronously copies data into the texture. + /// This variant copies into the entire texture. + /// + /// A pointer to an array of data to copy from. + /// The amount of data to copy from the array. + public void SetData(IntPtr dataPtr, uint dataLengthInBytes) { - SetData(new TextureSlice(this), data, dataLengthInBytes); + SetData(new TextureSlice(this), dataPtr, dataLengthInBytes); } + /// + /// Asynchronously copies data into the texture. + /// + /// The texture slice to copy into. + /// An array of data to copy into the texture. public unsafe void SetData(in TextureSlice textureSlice, T[] data) where T : unmanaged { var size = Marshal.SizeOf(); @@ -168,6 +220,11 @@ namespace MoonWorks.Graphics } } + /// + /// Asynchronously copies data into the texture. + /// This variant copies data into the entire texture. + /// + /// An array of data to copy into the texture. public unsafe void SetData(T[] data) where T : unmanaged { SetData(new TextureSlice(this), data); diff --git a/src/Graphics/State/ColorBlendState.cs b/src/Graphics/State/ColorBlendState.cs index 34082f9f..e9e81eca 100644 --- a/src/Graphics/State/ColorBlendState.cs +++ b/src/Graphics/State/ColorBlendState.cs @@ -1,5 +1,9 @@ namespace MoonWorks.Graphics { + /// + /// Describes how the graphics pipeline will blend colors. + /// You must provide one ColorTargetBlendState per color target in the pipeline. + /// public unsafe struct ColorBlendState { public bool LogicOpEnable; diff --git a/src/Graphics/State/ColorTargetBlendState.cs b/src/Graphics/State/ColorTargetBlendState.cs index b29545c4..d51e442c 100644 --- a/src/Graphics/State/ColorTargetBlendState.cs +++ b/src/Graphics/State/ColorTargetBlendState.cs @@ -4,13 +4,43 @@ namespace MoonWorks.Graphics { public struct ColorTargetBlendState { + /// + /// If disabled, no blending will occur. + /// public bool BlendEnable; + + /// + /// Selects which blend operation to use with alpha values. + /// public BlendOp AlphaBlendOp; + /// + /// Selects which blend operation to use with color values. + /// public BlendOp ColorBlendOp; + + /// + /// Specifies which of the RGBA components are enabled for writing. + /// public ColorComponentFlags ColorWriteMask; + + /// + /// Selects which blend factor is used to determine the alpha destination factor. + /// public BlendFactor DestinationAlphaBlendFactor; + + /// + /// Selects which blend factor is used to determine the color destination factor. + /// public BlendFactor DestinationColorBlendFactor; + + /// + /// Selects which blend factor is used to determine the alpha source factor. + /// public BlendFactor SourceAlphaBlendFactor; + + /// + /// Selects which blend factor is used to determine the color source factor. + /// public BlendFactor SourceColorBlendFactor; public static readonly ColorTargetBlendState Additive = new ColorTargetBlendState diff --git a/src/Graphics/State/DepthStencilState.cs b/src/Graphics/State/DepthStencilState.cs index 61d45b17..044df3d7 100644 --- a/src/Graphics/State/DepthStencilState.cs +++ b/src/Graphics/State/DepthStencilState.cs @@ -1,17 +1,53 @@ -using RefreshCS; - namespace MoonWorks.Graphics { + /// + /// Determines how data is written to and read from the depth/stencil buffer. + /// public struct DepthStencilState { + /// + /// If disabled, no depth culling will occur. + /// public bool DepthTestEnable; + + /// + /// Describes the stencil operation for back-facing primitives. + /// public StencilOpState BackStencilState; + + /// + /// Describes the stencil operation for front-facing primitives. + /// public StencilOpState FrontStencilState; + + /// + /// The comparison operator used in the depth test. + /// public CompareOp CompareOp; + + /// + /// If depth lies outside of these bounds the pixel will be culled. + /// public bool DepthBoundsTestEnable; + + /// + /// Specifies whether depth values will be written to the buffer during rendering. + /// public bool DepthWriteEnable; + + /// + /// The minimum depth value in the depth bounds test. + /// public float MinDepthBounds; + + /// + /// The maximum depth value in the depth bounds test. + /// public float MaxDepthBounds; + + /// + /// If disabled, no stencil culling will occur. + /// public bool StencilTestEnable; public static readonly DepthStencilState DepthReadWrite = new DepthStencilState diff --git a/src/Graphics/State/GraphicsPipelineLayoutInfo.cs b/src/Graphics/State/GraphicsPipelineLayoutInfo.cs index 405c4755..7a237bdf 100644 --- a/src/Graphics/State/GraphicsPipelineLayoutInfo.cs +++ b/src/Graphics/State/GraphicsPipelineLayoutInfo.cs @@ -1,5 +1,8 @@ namespace MoonWorks.Graphics { + /// + /// Describes how many samplers will be used in each shader stage. + /// public struct GraphicsPipelineLayoutInfo { public uint VertexSamplerBindingCount; diff --git a/src/Graphics/State/MultisampleState.cs b/src/Graphics/State/MultisampleState.cs index 18bd7d5a..a6915688 100644 --- a/src/Graphics/State/MultisampleState.cs +++ b/src/Graphics/State/MultisampleState.cs @@ -1,5 +1,8 @@ namespace MoonWorks.Graphics { + /// + /// Specifies how many samples should be used in rasterization. + /// public struct MultisampleState { public SampleCount MultisampleCount; diff --git a/src/Graphics/State/RasterizerState.cs b/src/Graphics/State/RasterizerState.cs index 18891430..ec669802 100644 --- a/src/Graphics/State/RasterizerState.cs +++ b/src/Graphics/State/RasterizerState.cs @@ -1,15 +1,49 @@ namespace MoonWorks.Graphics { + /// + /// Specifies how the rasterizer should be configured for a graphics pipeline. + /// public struct RasterizerState { + /// + /// Specifies whether front faces, back faces, none, or both should be culled. + /// public CullMode CullMode; + + /// + /// Specifies maximum depth bias of a fragment. Only applies if depth biasing is enabled. + /// public float DepthBiasClamp; + + /// + /// The constant depth value added to each fragment. Only applies if depth biasing is enabled. + /// public float DepthBiasConstantFactor; + + /// + /// Specifies whether depth biasing is enabled. Only applies if depth biasing is enabled. + /// public bool DepthBiasEnable; + + /// + /// Factor applied to a fragment's slope in depth bias calculations. Only applies if depth biasing is enabled. + /// public float DepthBiasSlopeFactor; public bool DepthClampEnable; + + /// + /// Specifies how triangles should be drawn. + /// public FillMode FillMode; + + /// + /// Specifies which triangle winding order is designated as front-facing. + /// public FrontFace FrontFace; + + /// + /// Describes the width of the line rendering in terms of pixels. + /// public float LineWidth; public static readonly RasterizerState CW_CullFront = new RasterizerState diff --git a/src/Graphics/State/ShaderStageState.cs b/src/Graphics/State/ShaderStageState.cs index 133b4a62..83ce53cd 100644 --- a/src/Graphics/State/ShaderStageState.cs +++ b/src/Graphics/State/ShaderStageState.cs @@ -1,5 +1,8 @@ namespace MoonWorks.Graphics { + /// + /// Specifies how the graphics pipeline will make use of a shader. + /// public struct ShaderStageState { public ShaderModule ShaderModule; diff --git a/src/Graphics/State/VertexInputState.cs b/src/Graphics/State/VertexInputState.cs index 216404d6..f80731a9 100644 --- a/src/Graphics/State/VertexInputState.cs +++ b/src/Graphics/State/VertexInputState.cs @@ -1,5 +1,8 @@ namespace MoonWorks.Graphics { + /// + /// Specifies how to interpet vertex data in a buffer to be passed to the vertex shader. + /// public struct VertexInputState { public VertexBinding[] VertexBindings; diff --git a/src/Graphics/State/ViewportState.cs b/src/Graphics/State/ViewportState.cs index 02bb35b6..1fd1c76b 100644 --- a/src/Graphics/State/ViewportState.cs +++ b/src/Graphics/State/ViewportState.cs @@ -1,5 +1,8 @@ namespace MoonWorks.Graphics { + /// + /// Describes the dimensions of viewports and scissor areas. + /// public struct ViewportState { public Viewport[] Viewports; diff --git a/src/Graphics/TextureSlice.cs b/src/Graphics/TextureSlice.cs index 7263d66e..de5b2253 100644 --- a/src/Graphics/TextureSlice.cs +++ b/src/Graphics/TextureSlice.cs @@ -2,6 +2,10 @@ namespace MoonWorks.Graphics { + /// + /// A texture slice specifies a subregion of a texture. + /// Many operations can use texture slices in place of textures for the sake of convenience. + /// public struct TextureSlice { public Texture Texture { get; }