From b026b9e81f0d06924815b65bcd5278f7af9eaf3b Mon Sep 17 00:00:00 2001 From: cosmonaut Date: Tue, 19 Sep 2023 13:19:41 -0700 Subject: [PATCH] add lots more doc comments --- src/Audio/AudioBuffer.cs | 6 ++- src/Audio/AudioDataOgg.cs | 9 +++++ src/Audio/AudioDataQoa.cs | 9 +++++ src/Audio/AudioDevice.cs | 3 ++ src/Audio/AudioEmitter.cs | 3 ++ src/Audio/AudioListener.cs | 3 ++ src/Audio/Format.cs | 3 ++ src/Audio/TransientVoice.cs | 4 +- src/Audio/Voice.cs | 3 ++ src/FrameLimiterSettings.cs | 13 +++++++ src/Graphics/Bindings/BufferBinding.cs | 3 ++ .../Bindings/TextureSamplerBinding.cs | 7 ++-- src/Graphics/GraphicsDevice.cs | 28 ++++++++++++- src/Graphics/IVertexType.cs | 6 +++ src/Graphics/RefreshEnums.cs | 20 ++++++++++ src/Graphics/Resources/Buffer.cs | 13 +++++-- src/Graphics/Resources/ComputePipeline.cs | 4 +- src/Graphics/Resources/Fence.cs | 9 ++--- src/Graphics/Resources/GraphicsPipeline.cs | 2 +- src/Graphics/Resources/Texture.cs | 5 ++- .../State/ColorAttachmentBlendState.cs | 3 ++ src/Graphics/State/ComputeShaderInfo.cs | 2 +- .../State/GraphicsPipelineCreateInfo.cs | 3 ++ src/Graphics/State/GraphicsShaderInfo.cs | 2 +- src/Graphics/State/SamplerCreateInfo.cs | 39 +++++++++++++++++++ src/Graphics/State/TextureCreateInfo.cs | 3 ++ src/Graphics/State/VertexInputState.cs | 2 +- src/Graphics/VertexBindingAndAttributes.cs | 4 +- src/Video/VideoAV1.cs | 3 ++ src/Video/VideoPlayer.cs | 24 +++++++++++- src/Window.cs | 14 +++++-- src/WindowCreateInfo.cs | 24 ++++++++++++ 32 files changed, 246 insertions(+), 30 deletions(-) diff --git a/src/Audio/AudioBuffer.cs b/src/Audio/AudioBuffer.cs index fdfb5e5b..6c79055c 100644 --- a/src/Audio/AudioBuffer.cs +++ b/src/Audio/AudioBuffer.cs @@ -4,7 +4,7 @@ using System.Runtime.InteropServices; namespace MoonWorks.Audio { /// - /// Contains raw audio data in the format specified by Format. + /// Contains raw audio data in a specified Format.
/// Submit this to a SourceVoice to play audio. /// public class AudioBuffer : AudioResource @@ -15,6 +15,10 @@ namespace MoonWorks.Audio public Format Format { get; } + /// + /// Create a new AudioBuffer. + /// + /// If true, the buffer data will be destroyed when this AudioBuffer is destroyed. public AudioBuffer( AudioDevice device, Format format, diff --git a/src/Audio/AudioDataOgg.cs b/src/Audio/AudioDataOgg.cs index dce9976b..d14d7159 100644 --- a/src/Audio/AudioDataOgg.cs +++ b/src/Audio/AudioDataOgg.cs @@ -58,6 +58,9 @@ namespace MoonWorks.Audio filledLengthInBytes = sampleCount * sizeof(float); } + /// + /// Prepares the Ogg data for streaming. + /// public override unsafe void Load() { if (!Loaded) @@ -84,6 +87,9 @@ namespace MoonWorks.Audio FAudio.stb_vorbis_seek(VorbisHandle, sampleFrame); } + /// + /// Unloads the Ogg data, freeing resources. + /// public override unsafe void Unload() { if (Loaded) @@ -96,6 +102,9 @@ namespace MoonWorks.Audio } } + /// + /// Loads an entire ogg file into an AudioBuffer. Useful for static audio. + /// public unsafe static AudioBuffer CreateBuffer(AudioDevice device, string filePath) { var filePointer = FAudio.stb_vorbis_open_filename(filePath, out var error, IntPtr.Zero); diff --git a/src/Audio/AudioDataQoa.cs b/src/Audio/AudioDataQoa.cs index 9bf30d6f..e54a3d2e 100644 --- a/src/Audio/AudioDataQoa.cs +++ b/src/Audio/AudioDataQoa.cs @@ -68,6 +68,9 @@ namespace MoonWorks.Audio filledLengthInBytes = (int) (sampleCount * sizeof(short)); } + /// + /// Prepares qoa data for streaming. + /// public override unsafe void Load() { if (!Loaded) @@ -93,6 +96,9 @@ namespace MoonWorks.Audio FAudio.qoa_seek_frame(QoaHandle, (int) sampleFrame); } + /// + /// Unloads the qoa data, freeing resources. + /// public override unsafe void Unload() { if (Loaded) @@ -105,6 +111,9 @@ namespace MoonWorks.Audio } } + /// + /// Loads the entire qoa file into an AudioBuffer. Useful for static audio. + /// public unsafe static AudioBuffer CreateBuffer(AudioDevice device, string filePath) { using var fileStream = new FileStream(filePath, FileMode.Open, FileAccess.Read); diff --git a/src/Audio/AudioDevice.cs b/src/Audio/AudioDevice.cs index 62129a8b..6fc081c1 100644 --- a/src/Audio/AudioDevice.cs +++ b/src/Audio/AudioDevice.cs @@ -4,6 +4,9 @@ using System.Threading; namespace MoonWorks.Audio { + /// + /// AudioDevice manages all audio-related concerns. + /// public class AudioDevice : IDisposable { public IntPtr Handle { get; } diff --git a/src/Audio/AudioEmitter.cs b/src/Audio/AudioEmitter.cs index 9dd38981..1a9c9833 100644 --- a/src/Audio/AudioEmitter.cs +++ b/src/Audio/AudioEmitter.cs @@ -4,6 +4,9 @@ using MoonWorks.Math.Float; namespace MoonWorks.Audio { + /// + /// An emitter for 3D spatial audio. + /// public class AudioEmitter : AudioResource { internal FAudio.F3DAUDIO_EMITTER emitterData; diff --git a/src/Audio/AudioListener.cs b/src/Audio/AudioListener.cs index 1309c160..e1217909 100644 --- a/src/Audio/AudioListener.cs +++ b/src/Audio/AudioListener.cs @@ -3,6 +3,9 @@ using MoonWorks.Math.Float; namespace MoonWorks.Audio { + /// + /// A listener for 3D spatial audio. Usually attached to a camera. + /// public class AudioListener : AudioResource { internal FAudio.F3DAUDIO_LISTENER listenerData; diff --git a/src/Audio/Format.cs b/src/Audio/Format.cs index 40d736e8..27244b29 100644 --- a/src/Audio/Format.cs +++ b/src/Audio/Format.cs @@ -8,6 +8,9 @@ namespace MoonWorks.Audio IEEE_FLOAT = 3 } + /// + /// Describes the format of audio data. Usually specified in an audio file's header information. + /// public record struct Format { public FormatTag Tag; diff --git a/src/Audio/TransientVoice.cs b/src/Audio/TransientVoice.cs index 9c747b6e..0b6e499c 100644 --- a/src/Audio/TransientVoice.cs +++ b/src/Audio/TransientVoice.cs @@ -1,8 +1,8 @@ namespace MoonWorks.Audio { /// - /// TransientVoice is intended for playing one-off sound effects that don't have a long term reference. - /// It will be automatically returned to the source voice pool once it is done playing back. + /// TransientVoice is intended for playing one-off sound effects that don't have a long term reference.
+ /// It will be automatically returned to the AudioDevice SourceVoice pool once it is done playing back. /// public class TransientVoice : SourceVoice, IPoolable { diff --git a/src/Audio/Voice.cs b/src/Audio/Voice.cs index e5bba154..d982f1bc 100644 --- a/src/Audio/Voice.cs +++ b/src/Audio/Voice.cs @@ -4,6 +4,9 @@ using EasingFunction = System.Func; namespace MoonWorks.Audio { + /// + /// Handles audio playback from audio buffer data. Can be configured with a variety of parameters. + /// public abstract unsafe class Voice : AudioResource { protected IntPtr handle; diff --git a/src/FrameLimiterSettings.cs b/src/FrameLimiterSettings.cs index bcf7eb2f..ed6e44dd 100644 --- a/src/FrameLimiterSettings.cs +++ b/src/FrameLimiterSettings.cs @@ -1,14 +1,27 @@ namespace MoonWorks { + /// + /// The Game's frame limiter mode. Specifies a maximum rendering frames per second value. + /// public enum FrameLimiterMode { + /// + /// The game will render at the maximum possible framerate that the computing resources allow.
+ /// Note that this may lead to overheating, resource starvation, etc. + /// Uncapped, + /// + /// The game will render no more than the specified frames per second. + /// Capped } public struct FrameLimiterSettings { public FrameLimiterMode Mode; + /// + /// If Mode is set to Uncapped, this is the maximum frames per second that will be rendered. + /// public int Cap; public FrameLimiterSettings( diff --git a/src/Graphics/Bindings/BufferBinding.cs b/src/Graphics/Bindings/BufferBinding.cs index 3d9f5112..4e318b67 100644 --- a/src/Graphics/Bindings/BufferBinding.cs +++ b/src/Graphics/Bindings/BufferBinding.cs @@ -1,5 +1,8 @@ namespace MoonWorks.Graphics { + /// + /// A buffer-offset pair to be used when binding vertex buffers. + /// public struct BufferBinding { public Buffer Buffer; diff --git a/src/Graphics/Bindings/TextureSamplerBinding.cs b/src/Graphics/Bindings/TextureSamplerBinding.cs index 06179bf5..ec2bf3da 100644 --- a/src/Graphics/Bindings/TextureSamplerBinding.cs +++ b/src/Graphics/Bindings/TextureSamplerBinding.cs @@ -1,7 +1,8 @@ -using System; - -namespace MoonWorks.Graphics +namespace MoonWorks.Graphics { + /// + /// A texture-sampler pair to be used when binding samplers. + /// public struct TextureSamplerBinding { public Texture Texture; diff --git a/src/Graphics/GraphicsDevice.cs b/src/Graphics/GraphicsDevice.cs index 0662d776..ed2262f8 100644 --- a/src/Graphics/GraphicsDevice.cs +++ b/src/Graphics/GraphicsDevice.cs @@ -5,6 +5,9 @@ using RefreshCS; namespace MoonWorks.Graphics { + /// + /// GraphicsDevice manages all graphics-related concerns. + /// public class GraphicsDevice : IDisposable { public IntPtr Handle { get; } @@ -21,7 +24,7 @@ namespace MoonWorks.Graphics private readonly HashSet> resources = new HashSet>(); private FencePool FencePool; - public GraphicsDevice( + internal GraphicsDevice( Backend preferredBackend, bool debugMode ) { @@ -77,6 +80,11 @@ namespace MoonWorks.Graphics FencePool = new FencePool(this); } + /// + /// Prepares a window so that frames can be presented to it. + /// + /// The desired presentation mode for the window. Roughly equivalent to V-Sync. + /// True if successfully claimed. public bool ClaimWindow(Window window, PresentMode presentMode) { var success = Conversions.ByteToBool( @@ -100,6 +108,9 @@ namespace MoonWorks.Graphics return success; } + /// + /// Unclaims a window, making it unavailable for presenting and freeing associated resources. + /// public void UnclaimWindow(Window window) { Refresh.Refresh_UnclaimWindow( @@ -109,8 +120,18 @@ namespace MoonWorks.Graphics window.Claimed = false; } + /// + /// Changes the present mode of a claimed window. Does nothing if the window is not claimed. + /// + /// + /// public void SetPresentMode(Window window, PresentMode presentMode) { + if (!window.Claimed) + { + return; + } + Refresh.Refresh_SetSwapchainPresentMode( Handle, window.Handle, @@ -118,6 +139,11 @@ namespace MoonWorks.Graphics ); } + /// + /// Acquires a command buffer. + /// This is the start of your rendering process. + /// + /// public CommandBuffer AcquireCommandBuffer() { return new CommandBuffer(this, Refresh.Refresh_AcquireCommandBuffer(Handle)); diff --git a/src/Graphics/IVertexType.cs b/src/Graphics/IVertexType.cs index cd055f2d..6e95e4d9 100644 --- a/src/Graphics/IVertexType.cs +++ b/src/Graphics/IVertexType.cs @@ -1,7 +1,13 @@ namespace MoonWorks.Graphics { + /// + /// Can be defined on your struct type to enable simplified vertex input state definition. + /// public interface IVertexType { + /// + /// An ordered list of the types in your vertex struct. + /// static abstract VertexElementFormat[] Formats { get; } } } diff --git a/src/Graphics/RefreshEnums.cs b/src/Graphics/RefreshEnums.cs index 7bb4fc06..81cc353e 100644 --- a/src/Graphics/RefreshEnums.cs +++ b/src/Graphics/RefreshEnums.cs @@ -2,11 +2,31 @@ namespace MoonWorks { + /// + /// Presentation mode for a window. + /// public enum PresentMode { + /// + /// Does not wait for v-blank to update the window. Can cause visible tearing. + /// Immediate, + /// + /// Waits for v-blank and uses a queue to hold present requests. + /// Allows for low latency while preventing tearing. + /// May not be supported on non-Vulkan non-Linux systems or older hardware. + /// Mailbox, + /// + /// Waits for v-blank and adds present requests to a queue. + /// Will probably cause latency. + /// Required to be supported by all compliant hardware. + /// FIFO, + /// + /// Usually waits for v-blank, but if v-blank has passed since last update will update immediately. + /// May cause visible tearing. + /// FIFORelaxed } } diff --git a/src/Graphics/Resources/Buffer.cs b/src/Graphics/Resources/Buffer.cs index 54503c0e..bf86c0da 100644 --- a/src/Graphics/Resources/Buffer.cs +++ b/src/Graphics/Resources/Buffer.cs @@ -59,7 +59,7 @@ namespace MoonWorks.Graphics /// /// Reads data out of a buffer and into a span. - /// This operation is only guaranteed to read up-to-date data if GraphicsDevice.Wait is called first. + /// This operation is only guaranteed to read up-to-date data if GraphicsDevice.Wait or GraphicsDevice.WaitForFences is called first. /// /// The span that data will be copied to. /// The length of the data to read. @@ -73,6 +73,11 @@ namespace MoonWorks.Graphics { Logger.LogWarn("Requested too many bytes from buffer!"); } + + if (dataLengthInBytes > data.Length) + { + Logger.LogWarn("Data length is larger than the provided Span!"); + } #endif fixed (T* ptr = data) @@ -88,7 +93,7 @@ namespace MoonWorks.Graphics /// /// 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. + /// This operation is only guaranteed to read up-to-date data if GraphicsDevice.Wait or GraphicsDevice.WaitForFences is called first. /// /// The span that data will be copied to. /// The length of the data to read. @@ -102,7 +107,7 @@ namespace MoonWorks.Graphics /// /// Reads data out of a buffer and into a span. - /// This operation is only guaranteed to read up-to-date data if GraphicsDevice.Wait is called first. + /// This operation is only guaranteed to read up-to-date data if GraphicsDevice.Wait or GraphicsDevice.WaitForFences is called first. /// Fills the span with as much data from the buffer as it can. /// /// The span that data will be copied to. @@ -116,7 +121,7 @@ namespace MoonWorks.Graphics /// /// 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. + /// This operation is only guaranteed to read up-to-date data if GraphicsDevice.Wait or GraphicsDevice.WaitForFences is called first. /// Fills the array with as much data from the buffer as it can. /// /// The span that data will be copied to. diff --git a/src/Graphics/Resources/ComputePipeline.cs b/src/Graphics/Resources/ComputePipeline.cs index e654f9bc..44545012 100644 --- a/src/Graphics/Resources/ComputePipeline.cs +++ b/src/Graphics/Resources/ComputePipeline.cs @@ -1,9 +1,11 @@ using RefreshCS; using System; -using System.Runtime.InteropServices; namespace MoonWorks.Graphics { + /// + /// Compute pipelines perform arbitrary parallel processing on input data. + /// public class ComputePipeline : GraphicsResource { protected override Action QueueDestroyFunction => Refresh.Refresh_QueueDestroyComputePipeline; diff --git a/src/Graphics/Resources/Fence.cs b/src/Graphics/Resources/Fence.cs index 68a3a704..ae59ddfb 100644 --- a/src/Graphics/Resources/Fence.cs +++ b/src/Graphics/Resources/Fence.cs @@ -4,11 +4,10 @@ using RefreshCS; namespace MoonWorks.Graphics { /// - /// Fences allow you to track the status of a submitted command buffer. - /// You should only acquire a Fence if you will need to track the command buffer. - /// You should make sure to call GraphicsDevice.ReleaseFence when done with a Fence to avoid memory growth. - /// - /// The Fence object itself is basically just a wrapper for the Refresh_Fence. + /// Fences allow you to track the status of a submitted command buffer.
+ /// You should only acquire a Fence if you will need to track the command buffer.
+ /// You should make sure to call GraphicsDevice.ReleaseFence when done with a Fence to avoid memory growth.
+ /// The Fence object itself is basically just a wrapper for the Refresh_Fence.
/// The internal handle is replaced so that we can pool Fence objects to manage garbage. /// public class Fence : GraphicsResource diff --git a/src/Graphics/Resources/GraphicsPipeline.cs b/src/Graphics/Resources/GraphicsPipeline.cs index 30b32603..a1e75067 100644 --- a/src/Graphics/Resources/GraphicsPipeline.cs +++ b/src/Graphics/Resources/GraphicsPipeline.cs @@ -5,7 +5,7 @@ using RefreshCS; namespace MoonWorks.Graphics { /// - /// Graphics pipelines encapsulate all of the render state in a single object. + /// 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 diff --git a/src/Graphics/Resources/Texture.cs b/src/Graphics/Resources/Texture.cs index 2ff9ca42..0af8454f 100644 --- a/src/Graphics/Resources/Texture.cs +++ b/src/Graphics/Resources/Texture.cs @@ -591,8 +591,9 @@ namespace MoonWorks.Graphics } /// - /// Asynchronously saves RGBA or BGRA pixel data to a file in PNG format. - /// Warning: this is expensive and will block to wait for data download from GPU! + /// Asynchronously saves RGBA or BGRA pixel data to a file in PNG format.
+ /// Warning: this is expensive and will block to wait for data download from GPU!
+ /// You can avoid blocking by calling this method from a thread. /// public unsafe void SavePNG(string path) { diff --git a/src/Graphics/State/ColorAttachmentBlendState.cs b/src/Graphics/State/ColorAttachmentBlendState.cs index 83204b57..0f5f610d 100644 --- a/src/Graphics/State/ColorAttachmentBlendState.cs +++ b/src/Graphics/State/ColorAttachmentBlendState.cs @@ -2,6 +2,9 @@ namespace MoonWorks.Graphics { + /// + /// Defines how color blending will be performed in a GraphicsPipeline. + /// public struct ColorAttachmentBlendState { /// diff --git a/src/Graphics/State/ComputeShaderInfo.cs b/src/Graphics/State/ComputeShaderInfo.cs index 9294a1c8..72fbbb7c 100644 --- a/src/Graphics/State/ComputeShaderInfo.cs +++ b/src/Graphics/State/ComputeShaderInfo.cs @@ -3,7 +3,7 @@ using System.Runtime.InteropServices; namespace MoonWorks.Graphics { /// - /// Information that the pipeline needs about a shader. + /// Information that the compute pipeline needs about a compute shader. /// public struct ComputeShaderInfo { diff --git a/src/Graphics/State/GraphicsPipelineCreateInfo.cs b/src/Graphics/State/GraphicsPipelineCreateInfo.cs index ca8fda9c..c46e60c5 100644 --- a/src/Graphics/State/GraphicsPipelineCreateInfo.cs +++ b/src/Graphics/State/GraphicsPipelineCreateInfo.cs @@ -1,5 +1,8 @@ namespace MoonWorks.Graphics { + /// + /// All of the information that is used to create a GraphicsPipeline. + /// public struct GraphicsPipelineCreateInfo { public DepthStencilState DepthStencilState; diff --git a/src/Graphics/State/GraphicsShaderInfo.cs b/src/Graphics/State/GraphicsShaderInfo.cs index 38b2bd33..a0cee035 100644 --- a/src/Graphics/State/GraphicsShaderInfo.cs +++ b/src/Graphics/State/GraphicsShaderInfo.cs @@ -3,7 +3,7 @@ namespace MoonWorks.Graphics { /// - /// Information that the pipeline needs about a shader. + /// Information that the pipeline needs about a graphics shader. /// public struct GraphicsShaderInfo { diff --git a/src/Graphics/State/SamplerCreateInfo.cs b/src/Graphics/State/SamplerCreateInfo.cs index bc5e958a..f6809415 100644 --- a/src/Graphics/State/SamplerCreateInfo.cs +++ b/src/Graphics/State/SamplerCreateInfo.cs @@ -2,21 +2,60 @@ namespace MoonWorks.Graphics { + /// + /// All of the information that is used to create a sampler. + /// public struct SamplerCreateInfo { + /// + /// Minification filter mode. Used when the image is downscaled. + /// public Filter MinFilter; + /// + /// Magnification filter mode. Used when the image is upscaled. + /// public Filter MagFilter; + /// + /// Filter mode applied to mipmap lookups. + /// public SamplerMipmapMode MipmapMode; + /// + /// Horizontal addressing mode. + /// public SamplerAddressMode AddressModeU; + /// + /// Vertical addressing mode. + /// public SamplerAddressMode AddressModeV; + /// + /// Depth addressing mode. + /// public SamplerAddressMode AddressModeW; + /// + /// Bias value added to mipmap level of detail calculation. + /// public float MipLodBias; + /// + /// Enables anisotropic filtering. + /// public bool AnisotropyEnable; + /// + /// Maximum anisotropy value. + /// public float MaxAnisotropy; public bool CompareEnable; public CompareOp CompareOp; + /// + /// Clamps the LOD value to a specified minimum. + /// public float MinLod; + /// + /// Clamps the LOD value to a specified maximum. + /// public float MaxLod; + /// + /// If an address mode is set to ClampToBorder, will replace color with this color when samples are outside the [0, 1) range. + /// public BorderColor BorderColor; public static readonly SamplerCreateInfo AnisotropicClamp = new SamplerCreateInfo diff --git a/src/Graphics/State/TextureCreateInfo.cs b/src/Graphics/State/TextureCreateInfo.cs index 9d15aa3b..7661aba0 100644 --- a/src/Graphics/State/TextureCreateInfo.cs +++ b/src/Graphics/State/TextureCreateInfo.cs @@ -2,6 +2,9 @@ namespace MoonWorks.Graphics { + /// + /// All of the information that is used to create a texture. + /// public struct TextureCreateInfo { public uint Width; diff --git a/src/Graphics/State/VertexInputState.cs b/src/Graphics/State/VertexInputState.cs index 466b1745..0097aee8 100644 --- a/src/Graphics/State/VertexInputState.cs +++ b/src/Graphics/State/VertexInputState.cs @@ -1,7 +1,7 @@ namespace MoonWorks.Graphics { /// - /// Specifies how to interpet vertex data in a buffer to be passed to the vertex shader. + /// Specifies how the vertex shader will interpet vertex data in a buffer. /// public struct VertexInputState { diff --git a/src/Graphics/VertexBindingAndAttributes.cs b/src/Graphics/VertexBindingAndAttributes.cs index 2651827f..cff9d55e 100644 --- a/src/Graphics/VertexBindingAndAttributes.cs +++ b/src/Graphics/VertexBindingAndAttributes.cs @@ -1,6 +1,8 @@ namespace MoonWorks.Graphics { - // This is a convenience structure for pairing a vertex binding with its associated attributes. + /// + /// A convenience structure for pairing a vertex binding with its associated attributes. + /// public struct VertexBindingAndAttributes { public VertexBinding VertexBinding { get; } diff --git a/src/Video/VideoAV1.cs b/src/Video/VideoAV1.cs index 38aebee8..9aaf157e 100644 --- a/src/Video/VideoAV1.cs +++ b/src/Video/VideoAV1.cs @@ -25,6 +25,9 @@ namespace MoonWorks.Video private int height; private Dav1dfile.PixelLayout pixelLayout; + /// + /// Opens an AV1 file so it can be loaded by VideoPlayer. You must also provide a playback framerate. + /// public VideoAV1(string filename, double framesPerSecond) { if (!File.Exists(filename)) diff --git a/src/Video/VideoPlayer.cs b/src/Video/VideoPlayer.cs index f7db51ac..826e7b1b 100644 --- a/src/Video/VideoPlayer.cs +++ b/src/Video/VideoPlayer.cs @@ -1,12 +1,13 @@ using System; using System.Diagnostics; using System.Threading.Tasks; -using System.Runtime.InteropServices; -using MoonWorks.Audio; using MoonWorks.Graphics; namespace MoonWorks.Video { + /// + /// A structure for continuous decoding of AV1 videos and rendering them into a texture. + /// public unsafe class VideoPlayer : IDisposable { public Texture RenderTexture { get; private set; } = null; @@ -44,6 +45,10 @@ namespace MoonWorks.Video timer = new Stopwatch(); } + /// + /// Prepares a VideoAV1 for decoding and rendering. + /// + /// public void Load(VideoAV1 video) { if (Video != video) @@ -100,6 +105,9 @@ namespace MoonWorks.Video } } + /// + /// Starts playing back and decoding the loaded video. + /// public void Play() { if (Video == null) { return; } @@ -114,6 +122,9 @@ namespace MoonWorks.Video State = VideoState.Playing; } + /// + /// Pauses playback and decoding of the currently playing video. + /// public void Pause() { if (Video == null) { return; } @@ -128,6 +139,9 @@ namespace MoonWorks.Video State = VideoState.Paused; } + /// + /// Stops and resets decoding of the currently playing video. + /// public void Stop() { if (Video == null) { return; } @@ -148,12 +162,18 @@ namespace MoonWorks.Video State = VideoState.Stopped; } + /// + /// Unloads the currently playing video. + /// public void Unload() { Stop(); Video = null; } + /// + /// Renders the video data into RenderTexture. + /// public void Render() { if (Video == null || State == VideoState.Stopped) diff --git a/src/Window.cs b/src/Window.cs index 163aa6e7..6ae5676b 100644 --- a/src/Window.cs +++ b/src/Window.cs @@ -6,9 +6,9 @@ using SDL2; namespace MoonWorks { /// - /// Represents a window in the client operating system. - /// Every Game has a MainWindow automatically. - /// You can create dditional Windows if you desire. They must be Claimed by the GraphicsDevice to be rendered to. + /// Represents a window in the client operating system.
+ /// Every Game has a MainWindow automatically.
+ /// You can create additional Windows if you desire. They must be Claimed by the GraphicsDevice to be rendered to. /// public class Window : IDisposable { @@ -69,6 +69,9 @@ namespace MoonWorks idLookup.Add(SDL.SDL_GetWindowID(Handle), this); } + /// + /// Changes the ScreenMode of this window. + /// public void SetScreenMode(ScreenMode screenMode) { SDL.SDL_WindowFlags windowFlag = 0; @@ -93,7 +96,7 @@ namespace MoonWorks } /// - /// Resizes the window. + /// Resizes the window.
/// Note that you are responsible for recreating any graphics resources that need to change as a result of the size change. /// /// @@ -131,6 +134,9 @@ namespace MoonWorks } } + /// + /// You can specify a method to run when the window size changes. + /// public void RegisterSizeChangeCallback(System.Action sizeChangeCallback) { SizeChangeCallback = sizeChangeCallback; diff --git a/src/WindowCreateInfo.cs b/src/WindowCreateInfo.cs index e930593e..44395850 100644 --- a/src/WindowCreateInfo.cs +++ b/src/WindowCreateInfo.cs @@ -1,13 +1,37 @@ namespace MoonWorks { + /// + /// All the information required for window creation. + /// public struct WindowCreateInfo { + /// + /// The name of the window that will be displayed in the operating system. + /// public string WindowTitle; + /// + /// The width of the window. + /// public uint WindowWidth; + /// + /// The height of the window. + /// public uint WindowHeight; + /// + /// Specifies if the window will be created in windowed mode or a fullscreen mode. + /// public ScreenMode ScreenMode; + /// + /// Specifies the presentation mode for the window. Roughly equivalent to V-Sync. + /// public PresentMode PresentMode; + /// + /// Whether the window can be resized using the operating system's window dragging feature. + /// public bool SystemResizable; + /// + /// Specifies if the window will open at the maximum desktop resolution. + /// public bool StartMaximized; public WindowCreateInfo(