document lots of graphics stuff

src/Graphics/RefreshEnums.cs

@@ -22,6 +22,9 @@ namespace MoonWorks.Graphics
         TriangleStrip
     }
 
+    /// <summary>
+    /// Describes the operation that a render pass will use when loading a render target.
+    /// </summary>
     public enum LoadOp
     {
         Load,
@@ -29,6 +32,9 @@ namespace MoonWorks.Graphics
         DontCare
     }
 
+    /// <summary>
+    /// Describes the operation that a render pass will use when storing a render target.
+    /// </summary>
     public enum StoreOp
     {
         Store,

src/Graphics/Resources/Buffer.cs

@@ -4,10 +4,19 @@ using RefreshCS;
 
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// Buffers are generic data containers that can be used by the GPU.
+    /// </summary>
     public class Buffer : GraphicsResource
     {
         protected override Action<IntPtr, IntPtr> QueueDestroyFunction => Refresh.Refresh_QueueDestroyBuffer;
 
+        /// <summary>
+        /// Creates a buffer.
+        /// </summary>
+        /// <param name="device">An initialized GraphicsDevice.</param>
+        /// <param name="usageFlags">Specifies how the buffer will be used.</param>
+        /// <param name="sizeInBytes">The length of the array. Cannot be resized.</param>
         public Buffer(
             GraphicsDevice device,
             BufferUsageFlags usageFlags,
@@ -21,6 +30,12 @@ namespace MoonWorks.Graphics
             );
         }
 
+        /// <summary>
+        /// Asynchronously copies data into the buffer.
+        /// </summary>
+        /// <param name="data">An array of data to copy into the buffer.</param>
+        /// <param name="offsetInElements">Specifies where to start copying out of the array.</param>
+        /// <param name="lengthInElements">Specifies how many elements to copy.</param>
         public unsafe void SetData<T>(
             T[] data,
             uint offsetInElements,
@@ -41,6 +56,11 @@ namespace MoonWorks.Graphics
             }
         }
 
+        /// <summary>
+        /// Asynchronously copies data into the buffer.
+        /// This variant of this method copies the entire array.
+        /// </summary>
+        /// <param name="data">An array of data to copy.</param>
         public unsafe void SetData<T>(
             T[] data
         ) where T : unmanaged
@@ -57,6 +77,12 @@ namespace MoonWorks.Graphics
             }
         }
 
+        /// <summary>
+        /// Asynchronously copies data into the buffer.
+        /// </summary>
+        /// <param name="data">A pointer to an array.</param>
+        /// <param name="offsetInBytes">Specifies where to start copying the data, in bytes.</param>
+        /// <param name="dataLengthInBytes">Specifies how many bytes of data to copy.</param>
         public void SetData(
             IntPtr data,
             uint offsetInBytes,
@@ -71,6 +97,12 @@ namespace MoonWorks.Graphics
             );
         }
 
+        /// <summary>
+        /// Asynchronously copies data into the buffer.
+        /// </summary>
+        /// <param name="data">A pointer to an array.</param>
+        /// <param name="offsetInBytes">Specifies where to start copying the data, in bytes.</param>
+        /// <param name="dataLengthInBytes">Specifies how many bytes of data to copy.</param>
         public unsafe void SetData<T>(
             T* data,
             uint offsetInElements,
@@ -86,7 +118,12 @@ namespace MoonWorks.Graphics
             );
         }
 
-        // NOTE: You want to wait on the device before calling this
+        /// <summary>
+        /// 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.
+        /// </summary>
+        /// <param name="data">The array that data will be copied to.</param>
+        /// <param name="dataLengthInBytes">The length of the data to read.</param>
         public unsafe void GetData<T>(
             T[] data,
             uint dataLengthInBytes

src/Graphics/Resources/Framebuffer.cs

@@ -4,6 +4,9 @@ using RefreshCS;
 
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// A framebuffer is a collection of render targets that is rendered to during a render pass.
+    /// </summary>
     public class Framebuffer : GraphicsResource
     {
         protected override Action<IntPtr, IntPtr> QueueDestroyFunction => Refresh.Refresh_QueueDestroyFramebuffer;
@@ -15,12 +18,21 @@ namespace MoonWorks.Graphics
 
         public RenderPass RenderPass { get; }
 
+        /// <summary>
+        /// Creates a framebuffer.
+        /// </summary>
+        /// <param name="device">An initialized GraphicsDevice.</param>
+        /// <param name="width">The width of the framebuffer.</param>
+        /// <param name="height">The height of the framebuffer.</param>
+        /// <param name="renderPass">The reference render pass for the framebuffer.</param>
+        /// <param name="depthStencilTarget">The depth stencil target. Can be null.</param>
+        /// <param name="colorTargets">Anywhere from 0-4 color targets can be provided.</param>
         public unsafe Framebuffer(
             GraphicsDevice device,
             uint width,
             uint height,
             RenderPass renderPass,
-            RenderTarget depthStencilTarget, /* can be NULL */
+            RenderTarget depthStencilTarget,
             params RenderTarget[] colorTargets
         ) : base(device)
         {

src/Graphics/Resources/GraphicsPipeline.cs

@@ -4,6 +4,10 @@ using RefreshCS;
 
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// Graphics pipelines encapsulate all of the render state in a single object.
+    /// These pipelines are bound before draw calls are issued.
+    /// </summary>
     public class GraphicsPipeline : GraphicsResource
     {
         protected override Action<IntPtr, IntPtr> QueueDestroyFunction => Refresh.Refresh_QueueDestroyGraphicsPipeline;

src/Graphics/Resources/RenderPass.cs

@@ -3,10 +3,18 @@ using RefreshCS;
 
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// A render pass describes the kind of render targets that will be used in rendering.
+    /// </summary>
     public class RenderPass : GraphicsResource
     {
         protected override Action<IntPtr, IntPtr> QueueDestroyFunction => Refresh.Refresh_QueueDestroyRenderPass;
 
+        /// <summary>
+        /// Creates a render pass using color target descriptions.
+        /// </summary>
+        /// <param name="device">An initialized GraphicsDevice.</param>
+        /// <param name="colorTargetDescriptions">Up to 4 color target descriptions may be provided.</param>
         public unsafe RenderPass(
             GraphicsDevice device,
             params ColorTargetDescription[] colorTargetDescriptions
@@ -23,6 +31,12 @@ namespace MoonWorks.Graphics
             }
         }
 
+        /// <summary>
+        /// Creates a render pass using a depth/stencil target description and optional color target descriptions.
+        /// </summary>
+        /// <param name="device">An initialized GraphicsDevice.</param>
+        /// <param name="depthStencilTargetDescription">A depth/stencil target description.</param>
+        /// <param name="colorTargetDescriptions">Up to 4 color target descriptions may be provided.</param>
         public unsafe RenderPass(
             GraphicsDevice device,
             in DepthStencilTargetDescription depthStencilTargetDescription,

src/Graphics/Resources/RenderTarget.cs

@@ -3,6 +3,9 @@ using RefreshCS;
 
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// A render target is a structure that wraps a texture so that it can be rendered to.
+    /// </summary>
     public class RenderTarget : GraphicsResource
     {
         public TextureSlice TextureSlice { get; }
@@ -10,6 +13,17 @@ namespace MoonWorks.Graphics
 
         protected override Action<IntPtr, IntPtr> QueueDestroyFunction => Refresh.Refresh_QueueDestroyRenderTarget;
 
+        /// <summary>
+        /// Creates a render target backed by a texture.
+        /// </summary>
+        /// <param name="device">An initialized GraphicsDevice.</param>
+        /// <param name="width">The width of the render target.</param>
+        /// <param name="height">The height of the render target.</param>
+        /// <param name="format">The format of the render target.</param>
+        /// <param name="canBeSampled">Whether the render target can be used by a sampler.</param>
+        /// <param name="sampleCount">The multisample count of the render target.</param>
+        /// <param name="levelCount">The mip level of the render target.</param>
+        /// <returns></returns>
         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)
+        /// <summary>
+        /// Creates a render target using a texture slice and an optional sample count.
+        /// </summary>
+        /// <param name="device">An initialized GraphicsDevice.</param>
+        /// <param name="textureSlice">The texture slice that will be rendered to.</param>
+        /// <param name="sampleCount">The desired multisample count of the render target.</param>
+        public RenderTarget(
+            GraphicsDevice device,
+            in TextureSlice textureSlice,
+            SampleCount sampleCount = SampleCount.One
+        ) : base(device)
         {
             Handle = Refresh.Refresh_CreateRenderTarget(
                 device.Handle,

src/Graphics/Resources/Sampler.cs

@@ -3,6 +3,9 @@ using RefreshCS;
 
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// A sampler specifies how a texture will be sampled in a shader.
+    /// </summary>
     public class Sampler : GraphicsResource
     {
         protected override Action<IntPtr, IntPtr> QueueDestroyFunction => Refresh.Refresh_QueueDestroySampler;

src/Graphics/Resources/ShaderModule.cs

@@ -1,9 +1,11 @@
 using RefreshCS;
 using System;
-using System.IO;
 
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// Shader modules expect input in SPIR-V bytecode format.
+    /// </summary>
     public class ShaderModule : GraphicsResource
     {
         protected override Action<IntPtr, IntPtr> QueueDestroyFunction => Refresh.Refresh_QueueDestroyShaderModule;

src/Graphics/Resources/Texture.cs

@@ -5,6 +5,9 @@ using RefreshCS;
 
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// A container for pixel data.
+    /// </summary>
     public class Texture : GraphicsResource
     {
         public uint Width { get; }
@@ -48,6 +51,16 @@ namespace MoonWorks.Graphics
             }
         }
 
+        /// <summary>
+        /// Creates a 2D texture.
+        /// </summary>
+        /// <param name="device">An initialized GraphicsDevice.</param>
+        /// <param name="width">The width of the texture.</param>
+        /// <param name="height">The height of the texture.</param>
+        /// <param name="format">The format of the texture.</param>
+        /// <param name="usageFlags">Specifies how the texture will be used.</param>
+        /// <param name="sampleCount">Specifies the multisample count.</param>
+        /// <param name="levelCount">Specifies the number of mip levels.</param>
         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);
         }
 
+        /// <summary>
+        /// Creates a 3D texture.
+        /// </summary>
+        /// <param name="device">An initialized GraphicsDevice.</param>
+        /// <param name="width">The width of the texture.</param>
+        /// <param name="height">The height of the texture.</param>
+        /// <param name="depth">The depth of the texture.</param>
+        /// <param name="format">The format of the texture.</param>
+        /// <param name="usageFlags">Specifies how the texture will be used.</param>
+        /// <param name="sampleCount">Specifies the multisample count.</param>
+        /// <param name="levelCount">Specifies the number of mip levels.</param>
         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);
         }
 
+        /// <summary>
+        /// Creates a cube texture.
+        /// </summary>
+        /// <param name="device">An initialized GraphicsDevice.</param>
+        /// <param name="size">The length of one side of the cube.</param>
+        /// <param name="format">The format of the texture.</param>
+        /// <param name="usageFlags">Specifies how the texture will be used.</param>
+        /// <param name="sampleCount">Specifies the multisample count.</param>
+        /// <param name="levelCount">Specifies the number of mip levels.</param>
         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);
         }
 
+        /// <summary>
+        /// Creates a new texture using a TextureCreateInfo struct.
+        /// </summary>
+        /// <param name="device">An initialized GraphicsDevice.</param>
+        /// <param name="textureCreateInfo">The parameters to use when creating the texture.</param>
         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)
+        /// <summary>
+        /// Asynchronously copies data into the texture.
+        /// </summary>
+        /// <param name="textureSlice">The texture slice to copy into.</param>
+        /// <param name="dataPtr">A pointer to an array of data to copy from.</param>
+        /// <param name="dataLengthInBytes">The amount of data to copy from the array.</param>
+        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)
+        /// <summary>
+        /// Asynchronously copies data into the texture.
+        /// This variant copies into the entire texture.
+        /// </summary>
+        /// <param name="dataPtr">A pointer to an array of data to copy from.</param>
+        /// <param name="dataLengthInBytes">The amount of data to copy from the array.</param>
+        public void SetData(IntPtr dataPtr, uint dataLengthInBytes)
         {
-            SetData(new TextureSlice(this), data, dataLengthInBytes);
+            SetData(new TextureSlice(this), dataPtr, dataLengthInBytes);
         }
 
+        /// <summary>
+        /// Asynchronously copies data into the texture.
+        /// </summary>
+        /// <param name="textureSlice">The texture slice to copy into.</param>
+        /// <param name="data">An array of data to copy into the texture.</param>
         public unsafe void SetData<T>(in TextureSlice textureSlice, T[] data) where T : unmanaged
         {
             var size = Marshal.SizeOf<T>();
@@ -168,6 +220,11 @@ namespace MoonWorks.Graphics
             }
         }
 
+        /// <summary>
+        /// Asynchronously copies data into the texture.
+        /// This variant copies data into the entire texture.
+        /// </summary>
+        /// <param name="data">An array of data to copy into the texture.</param>
         public unsafe void SetData<T>(T[] data) where T : unmanaged
         {
             SetData(new TextureSlice(this), data);

src/Graphics/State/ColorBlendState.cs

@@ -1,5 +1,9 @@
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// Describes how the graphics pipeline will blend colors.
+    /// You must provide one ColorTargetBlendState per color target in the pipeline.
+    /// </summary>
     public unsafe struct ColorBlendState
     {
         public bool LogicOpEnable;

src/Graphics/State/ColorTargetBlendState.cs

@@ -4,13 +4,43 @@ namespace MoonWorks.Graphics
 {
     public struct ColorTargetBlendState
     {
+        /// <summary>
+        /// If disabled, no blending will occur.
+        /// </summary>
         public bool BlendEnable;
+
+        /// <summary>
+        /// Selects which blend operation to use with alpha values.
+        /// </summary>
         public BlendOp AlphaBlendOp;
+        /// <summary>
+        /// Selects which blend operation to use with color values.
+        /// </summary>
         public BlendOp ColorBlendOp;
+
+        /// <summary>
+        /// Specifies which of the RGBA components are enabled for writing.
+        /// </summary>
         public ColorComponentFlags ColorWriteMask;
+
+        /// <summary>
+        /// Selects which blend factor is used to determine the alpha destination factor.
+        /// </summary>
         public BlendFactor DestinationAlphaBlendFactor;
+
+        /// <summary>
+        /// Selects which blend factor is used to determine the color destination factor.
+        /// </summary>
         public BlendFactor DestinationColorBlendFactor;
+
+        /// <summary>
+        /// Selects which blend factor is used to determine the alpha source factor.
+        /// </summary>
         public BlendFactor SourceAlphaBlendFactor;
+
+        /// <summary>
+        /// Selects which blend factor is used to determine the color source factor.
+        /// </summary>
         public BlendFactor SourceColorBlendFactor;
 
         public static readonly ColorTargetBlendState Additive = new ColorTargetBlendState

src/Graphics/State/DepthStencilState.cs

@@ -1,17 +1,53 @@
-using RefreshCS;
-
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// Determines how data is written to and read from the depth/stencil buffer.
+    /// </summary>
     public struct DepthStencilState
     {
+        /// <summary>
+        /// If disabled, no depth culling will occur.
+        /// </summary>
         public bool DepthTestEnable;
+
+        /// <summary>
+        /// Describes the stencil operation for back-facing primitives.
+        /// </summary>
         public StencilOpState BackStencilState;
+
+        /// <summary>
+        /// Describes the stencil operation for front-facing primitives.
+        /// </summary>
         public StencilOpState FrontStencilState;
+
+        /// <summary>
+        /// The comparison operator used in the depth test.
+        /// </summary>
         public CompareOp CompareOp;
+
+        /// <summary>
+        /// If depth lies outside of these bounds the pixel will be culled.
+        /// </summary>
         public bool DepthBoundsTestEnable;
+
+        /// <summary>
+        /// Specifies whether depth values will be written to the buffer during rendering.
+        /// </summary>
         public bool DepthWriteEnable;
+
+        /// <summary>
+        /// The minimum depth value in the depth bounds test.
+        /// </summary>
         public float MinDepthBounds;
+
+        /// <summary>
+        /// The maximum depth value in the depth bounds test.
+        /// </summary>
         public float MaxDepthBounds;
+
+        /// <summary>
+        /// If disabled, no stencil culling will occur.
+        /// </summary>
         public bool StencilTestEnable;
 
         public static readonly DepthStencilState DepthReadWrite = new DepthStencilState

src/Graphics/State/GraphicsPipelineLayoutInfo.cs

@@ -1,5 +1,8 @@
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// Describes how many samplers will be used in each shader stage.
+    /// </summary>
     public struct GraphicsPipelineLayoutInfo
     {
         public uint VertexSamplerBindingCount;

src/Graphics/State/MultisampleState.cs

@@ -1,5 +1,8 @@
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// Specifies how many samples should be used in rasterization.
+    /// </summary>
     public struct MultisampleState
     {
         public SampleCount MultisampleCount;

src/Graphics/State/RasterizerState.cs

@@ -1,15 +1,49 @@
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// Specifies how the rasterizer should be configured for a graphics pipeline.
+    /// </summary>
     public struct RasterizerState
     {
+        /// <summary>
+        /// Specifies whether front faces, back faces, none, or both should be culled.
+        /// </summary>
         public CullMode CullMode;
+
+        /// <summary>
+        /// Specifies maximum depth bias of a fragment. Only applies if depth biasing is enabled.
+        /// </summary>
         public float DepthBiasClamp;
+
+        /// <summary>
+        /// The constant depth value added to each fragment. Only applies if depth biasing is enabled.
+        /// </summary>
         public float DepthBiasConstantFactor;
+
+        /// <summary>
+        /// Specifies whether depth biasing is enabled. Only applies if depth biasing is enabled.
+        /// </summary>
         public bool DepthBiasEnable;
+
+        /// <summary>
+        /// Factor applied to a fragment's slope in depth bias calculations. Only applies if depth biasing is enabled.
+        /// </summary>
         public float DepthBiasSlopeFactor;
         public bool DepthClampEnable;
+
+        /// <summary>
+        /// Specifies how triangles should be drawn.
+        /// </summary>
         public FillMode FillMode;
+
+        /// <summary>
+        /// Specifies which triangle winding order is designated as front-facing.
+        /// </summary>
         public FrontFace FrontFace;
+
+        /// <summary>
+        /// Describes the width of the line rendering in terms of pixels.
+        /// </summary>
         public float LineWidth;
 
         public static readonly RasterizerState CW_CullFront = new RasterizerState

src/Graphics/State/ShaderStageState.cs

@@ -1,5 +1,8 @@
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// Specifies how the graphics pipeline will make use of a shader.
+    /// </summary>
     public struct ShaderStageState
     {
         public ShaderModule ShaderModule;

src/Graphics/State/VertexInputState.cs

@@ -1,5 +1,8 @@
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// Specifies how to interpet vertex data in a buffer to be passed to the vertex shader.
+    /// </summary>
     public struct VertexInputState
     {
         public VertexBinding[] VertexBindings;

src/Graphics/State/ViewportState.cs

@@ -1,5 +1,8 @@
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// Describes the dimensions of viewports and scissor areas.
+    /// </summary>
     public struct ViewportState
     {
         public Viewport[] Viewports;

src/Graphics/TextureSlice.cs

@@ -2,6 +2,10 @@
 
 namespace MoonWorks.Graphics
 {
+    /// <summary>
+    /// A texture slice specifies a subregion of a texture.
+    /// Many operations can use texture slices in place of textures for the sake of convenience.
+    /// </summary>
     public struct TextureSlice
     {
         public Texture Texture { get; }