document lots of graphics stuff

main
cosmonaut 2021-02-24 12:43:35 -08:00
parent 72c676a1e0
commit b928257d3c
19 changed files with 298 additions and 16 deletions

View File

@ -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,

View File

@ -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

View File

@ -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)
{

View File

@ -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;

View File

@ -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,

View File

@ -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,

View File

@ -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;

View File

@ -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;

View File

@ -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);

View File

@ -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;

View File

@ -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

View File

@ -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

View File

@ -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;

View File

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

View File

@ -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

View File

@ -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;

View File

@ -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;

View File

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

View File

@ -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; }