diff --git a/MonoGame.Framework/Graphics/GraphicsDevice.cs b/MonoGame.Framework/Graphics/GraphicsDevice.cs index 8159e9cd0cb..aae397c0fc2 100644 --- a/MonoGame.Framework/Graphics/GraphicsDevice.cs +++ b/MonoGame.Framework/Graphics/GraphicsDevice.cs @@ -12,6 +12,10 @@ namespace Microsoft.Xna.Framework.Graphics { + /// + /// Performs primitive-based rendering, creates resources, + /// handles system-level variables, adjusts gamma ramp levels, and creates shaders. + /// public partial class GraphicsDevice : IDisposable { /// @@ -86,12 +90,26 @@ public partial class GraphicsDevice : IDisposable internal GraphicsCapabilities GraphicsCapabilities { get; private set; } + /// + /// Gets the collection of vertex textures that support texture lookup + /// in the vertex shader using the texldl statement. + /// The vertex engine contains four texture sampler stages. + /// public TextureCollection VertexTextures { get; private set; } + /// + /// Returns the collection of vertex sampler states. + /// public SamplerStateCollection VertexSamplerStates { get; private set; } + /// + /// Returns the collection of textures that have been assigned to the texture stages of the device. + /// public TextureCollection Textures { get; private set; } + /// + /// Retrieves a collection of objects for the current . + /// public SamplerStateCollection SamplerStates { get; private set; } /// @@ -138,12 +156,37 @@ private bool PixelShaderDirty // collected by holding a strong reference to it in this list. private readonly List _resources = new List(); - // TODO Graphics Device events need implementing - public event EventHandler DeviceLost; + // TODO Graphics Device events need implementing + /// + /// Occurs when a GraphicsDevice is about to be lost (for example, immediately before a reset). + /// + public event EventHandler DeviceLost; + + /// + /// Occurs after a GraphicsDevice is reset, allowing an application to recreate all resources. + /// public event EventHandler DeviceReset; + + /// + /// Occurs when a GraphicsDevice is resetting, + /// allowing the application to cancel the default handling of the reset. + /// public event EventHandler DeviceResetting; + + /// + /// Occurs when a resource is created. + /// public event EventHandler ResourceCreated; + + /// + /// Occurs when a resource is destroyed. + /// public event EventHandler ResourceDestroyed; + + /// + /// Occurs when is called + /// or when this object is finalized and collected by the garbage collector. + /// public event EventHandler Disposing; internal event EventHandler PresentationChanged; @@ -152,6 +195,9 @@ private bool PixelShaderDirty internal int MaxTextureSlots; internal int MaxVertexTextureSlots; + /// + /// Gets a value that indicates whether the object is disposed. + /// public bool IsDisposed { get @@ -160,6 +206,9 @@ public bool IsDisposed } } + /// + /// Gets a value that indicates whether the associated content was lost. + /// public bool IsContentLost { get { // We will just return IsDisposed for now @@ -186,6 +235,9 @@ internal DepthFormat ActiveDepthFormat } } + /// + /// Gets the graphics adapter. + /// public GraphicsAdapter Adapter { get; @@ -290,8 +342,7 @@ private void Setup() #endif // Initialize the main viewport - _viewport = new Viewport (0, 0, - DisplayMode.Width, DisplayMode.Height); + _viewport = new Viewport (0, 0, DisplayMode.Width, DisplayMode.Height); _viewport.MaxDepth = 1.0f; PlatformSetup(); @@ -324,6 +375,7 @@ private void Setup() EffectCache = new Dictionary(); } + /// ~GraphicsDevice() { Dispose(false); @@ -388,6 +440,10 @@ internal void Initialize() ApplyRenderTargets(null); } + /// + /// Gets or sets rasterizer state. + /// The default value is . + /// public RasterizerState RasterizerState { get @@ -446,6 +502,10 @@ public Color BlendFactor } } + /// + /// Gets or sets a system-defined instance of a blend state object initialized for alpha blending. + /// The default value is . + /// public BlendState BlendState { get { return _blendState; } @@ -487,6 +547,10 @@ public BlendState BlendState } } + /// + /// Gets or sets a system-defined instance of a depth-stencil state object. + /// The default value is . + /// public DepthStencilState DepthStencilState { get { return _depthStencilState; } @@ -540,6 +604,10 @@ internal void ApplyState(bool applyShaders) PlatformApplyState(applyShaders); } + /// + /// Clears resource buffers. + /// + /// Set this color value in all buffers. public void Clear(Color color) { var options = ClearOptions.Target; @@ -553,6 +621,11 @@ public void Clear(Color color) } } + /// + /// Set this color value in all buffers. + /// Options for clearing a buffer. + /// Set this depth value in the buffer. + /// Set this stencil value in the buffer. public void Clear(ClearOptions options, Color color, float depth, int stencil) { PlatformClear(options, color.ToVector4(), depth, stencil); @@ -563,7 +636,8 @@ public void Clear(ClearOptions options, Color color, float depth, int stencil) } } - public void Clear(ClearOptions options, Vector4 color, float depth, int stencil) + /// + public void Clear(ClearOptions options, Vector4 color, float depth, int stencil) { PlatformClear(options, color, depth, stencil); @@ -573,12 +647,14 @@ public void Clear(ClearOptions options, Vector4 color, float depth, int stencil) } } + /// public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } + /// protected virtual void Dispose(bool disposing) { if (!_isDisposed) @@ -643,6 +719,11 @@ internal void RemoveResourceReference(WeakReference resourceReference) } } + /// + /// Presents the display with the contents of the next buffer + /// in the sequence of back buffers owned by the . + /// + /// A render target is active. public void Present() { // We cannot present with a RT set on the device. @@ -662,6 +743,9 @@ public void Present(Rectangle? sourceRectangle, Rectangle? destinationRectangle, partial void PlatformReset(); + /// + /// Resets the presentation parameters for the current . + /// public void Reset() { PlatformReset(); @@ -675,6 +759,13 @@ public void Reset() EventHelpers.Raise(this, DeviceReset, EventArgs.Empty); } + /// + /// Resets the current with the specified . + /// + /// Presentation parameters to set. + /// + /// is + /// public void Reset(PresentationParameters presentationParameters) { if (presentationParameters == null) @@ -715,6 +806,9 @@ internal void OnDeviceReset() EventHelpers.Raise(this, DeviceReset, EventArgs.Empty); } + /// + /// Retrieves the display mode's spatial resolution, color resolution, and refresh frequency. + /// public DisplayMode DisplayMode { get @@ -723,6 +817,9 @@ public DisplayMode DisplayMode } } + /// + /// Retrieves the status of the device. + /// public GraphicsDeviceStatus GraphicsDeviceStatus { get @@ -731,12 +828,18 @@ public GraphicsDeviceStatus GraphicsDeviceStatus } } + /// + /// Gets the presentation parameters associated with this graphics device. + /// public PresentationParameters PresentationParameters { get; private set; } + /// + /// Gets or sets a viewport identifying the portion of the render target to receive draw calls. + /// public Viewport Viewport { get @@ -752,11 +855,18 @@ public Viewport Viewport } private readonly GraphicsProfile _graphicsProfile; + /// + /// Gets the graphics profile. + /// The default value is . + /// public GraphicsProfile GraphicsProfile { get { return _graphicsProfile; } } + /// + /// Gets or sets the rectangle used for scissor testing. By default, the size matches the render target size. + /// public Rectangle ScissorRectangle { get @@ -774,6 +884,9 @@ public Rectangle ScissorRectangle } } + /// + /// Gets the amount of render targets bound to this device. + /// public int RenderTargetCount { get @@ -782,6 +895,13 @@ public int RenderTargetCount } } + /// + /// Sets a new render target for this . + /// + /// + /// A new render target for the device, or + /// to set the device render target to the back buffer of the device. + /// public void SetRenderTarget(RenderTarget2D renderTarget) { if (renderTarget == null) @@ -795,6 +915,9 @@ public void SetRenderTarget(RenderTarget2D renderTarget) } } + /// + /// + /// The cube map face type. public void SetRenderTarget(RenderTargetCube renderTarget, CubeMapFace cubeMapFace) { if (renderTarget == null) @@ -808,6 +931,10 @@ public void SetRenderTarget(RenderTargetCube renderTarget, CubeMapFace cubeMapFa } } + /// + /// Sets an array of render targets. + /// + /// An array of render targets. public void SetRenderTargets(params RenderTargetBinding[] renderTargets) { // Avoid having to check for null and zero length. @@ -906,6 +1033,10 @@ internal void ApplyRenderTargets(RenderTargetBinding[] renderTargets) Clear(DiscardColor); } + /// + /// Gets render target surfaces. + /// + /// An array of bound render targets. public RenderTargetBinding[] GetRenderTargets() { // Return a correctly sized copy our internal array. @@ -914,12 +1045,23 @@ public RenderTargetBinding[] GetRenderTargets() return bindings; } + /// + /// Gets render target surfaces. + /// + /// + /// When this method returns, contains an array of that description of bound render targets. + /// This parameter is treated as uninitialized. + /// public void GetRenderTargets(RenderTargetBinding[] outTargets) { Debug.Assert(outTargets.Length == _currentRenderTargetCount, "Invalid outTargets array length!"); Array.Copy(_currentRenderTargetBindings, outTargets, _currentRenderTargetCount); } + /// + /// Sets or binds a vertex buffer to a device. + /// + /// A vertex buffer. public void SetVertexBuffer(VertexBuffer vertexBuffer) { _vertexBuffersDirty |= (vertexBuffer == null) @@ -927,6 +1069,13 @@ public void SetVertexBuffer(VertexBuffer vertexBuffer) : _vertexBuffers.Set(vertexBuffer, 0); } + /// + /// + /// The offset (in bytes) from the beginning of the buffer. + /// + /// is less than 0 + /// OR is greater than or equal to .VertexCount. + /// public void SetVertexBuffer(VertexBuffer vertexBuffer, int vertexOffset) { // Validate vertexOffset. @@ -942,6 +1091,13 @@ public void SetVertexBuffer(VertexBuffer vertexBuffer, int vertexOffset) : _vertexBuffers.Set(vertexBuffer, vertexOffset); } + /// + /// Sets the vertex buffers. + /// + /// An array of vertex buffers. + /// + /// Length of is more than max allowed number of vertex buffers. + /// public void SetVertexBuffers(params VertexBufferBinding[] vertexBuffers) { if (vertexBuffers == null || vertexBuffers.Length == 0) @@ -969,6 +1125,9 @@ private void SetIndexBuffer(IndexBuffer indexBuffer) _indexBufferDirty = true; } + /// + /// Gets or sets index data. The default value is . + /// public IndexBuffer Indices { set { SetIndexBuffer(value); } get { return _indexBuffer; } } internal Shader VertexShader @@ -1009,6 +1168,9 @@ internal void SetConstantBuffer(ShaderStage stage, int slot, ConstantBuffer buff _pixelConstantBuffers[slot] = buffer; } + /// + /// Gets a value that indicates whether the resources were lost. + /// public bool ResourcesLost { get; set; } /// @@ -1370,6 +1532,7 @@ public void DrawInstancedPrimitives(PrimitiveType primitiveType, int baseVertex, /// The format is whatever the current format of the backbuffer is. /// /// A byte[] of size (ViewPort.Width * ViewPort.Height * 4) + /// Array of data. public void GetBackBufferData(T[] data) where T : struct { if (data == null) @@ -1377,11 +1540,29 @@ public void GetBackBufferData(T[] data) where T : struct GetBackBufferData(null, data, 0, data.Length); } + /// + /// A byte[] of size (ViewPort.Width * ViewPort.Height * 4) + /// Array of data. + /// The first element to use. + /// The number of elements to use. public void GetBackBufferData(T[] data, int startIndex, int elementCount) where T : struct { GetBackBufferData(null, data, startIndex, elementCount); } + /// + /// A byte[] of size (ViewPort.Width * ViewPort.Height * 4) + /// + /// The section of the back buffer to copy. + /// indicates the data will be copied from the entire back buffer. + /// + /// Array of data. + /// The first element to use. + /// The number of elements to use. + /// + /// is + /// + /// public void GetBackBufferData(Rectangle? rect, T[] data, int startIndex, int elementCount) where T : struct { diff --git a/MonoGame.Framework/Graphics/GraphicsResource.cs b/MonoGame.Framework/Graphics/GraphicsResource.cs index d1c50611580..eac6c850ec2 100644 --- a/MonoGame.Framework/Graphics/GraphicsResource.cs +++ b/MonoGame.Framework/Graphics/GraphicsResource.cs @@ -7,6 +7,9 @@ namespace Microsoft.Xna.Framework.Graphics { + /// + /// Queries and prepares resources. + /// public abstract class GraphicsResource : IDisposable { bool disposed; @@ -23,6 +26,7 @@ internal GraphicsResource() } + /// ~GraphicsResource() { // Pass false so the managed objects are not released @@ -40,6 +44,7 @@ internal protected virtual void GraphicsDeviceResetting() } + /// public void Dispose() { // Dispose of managed objects as well @@ -80,8 +85,15 @@ protected virtual void Dispose(bool disposing) } } + /// + /// Occurs when is called + /// or when this object is finalized and collected by the garbage collector. + /// public event EventHandler Disposing; - + + /// + /// Gets the associated with this . + /// public GraphicsDevice GraphicsDevice { get @@ -110,7 +122,10 @@ internal set graphicsDevice.AddResourceReference(_selfReference); } } - + + /// + /// Gets a value that indicates whether the object is disposed. + /// public bool IsDisposed { get @@ -118,11 +133,20 @@ public bool IsDisposed return disposed; } } - + + /// + /// Gets the name of the resource. + /// public string Name { get; set; } - + + /// + /// Gets the resource tags for this resource. + /// public Object Tag { get; set; } + /// + /// Gets a string representation of the current instance. + /// public override string ToString() { return string.IsNullOrEmpty(Name) ? base.ToString() : Name; diff --git a/MonoGame.Framework/GraphicsDeviceManager.cs b/MonoGame.Framework/GraphicsDeviceManager.cs index 6f088b35d55..4bc23cd25c4 100644 --- a/MonoGame.Framework/GraphicsDeviceManager.cs +++ b/MonoGame.Framework/GraphicsDeviceManager.cs @@ -16,7 +16,6 @@ public partial class GraphicsDeviceManager : IGraphicsDeviceService, IDisposable private readonly Game _game; private GraphicsDevice _graphicsDevice; private bool _initialized = false; - private int _preferredBackBufferHeight; private int _preferredBackBufferWidth; private SurfaceFormat _preferredBackBufferFormat; @@ -30,6 +29,7 @@ public partial class GraphicsDeviceManager : IGraphicsDeviceService, IDisposable private bool _preferHalfPixelOffset = false; private bool _wantFullScreen; private GraphicsProfile _graphicsProfile; + // dirty flag for ApplyChanges private bool _shouldApplyChanges; @@ -96,6 +96,7 @@ public GraphicsDeviceManager(Game game) _game.Services.AddService(typeof(IGraphicsDeviceService), this); } + /// ~GraphicsDeviceManager() { Dispose(false); @@ -149,6 +150,13 @@ void IGraphicsDeviceManager.CreateDevice() CreateDevice(); } + /// + /// Begins the drawing process. + /// + /// + /// if the drawing process begins successfully; + /// otherwise. + /// public bool BeginDraw() { if (_graphicsDevice == null) @@ -158,6 +166,9 @@ public bool BeginDraw() return true; } + /// + /// Ends the drawing process and calls for the current graphics device. + /// public void EndDraw() { if (_graphicsDevice != null && _drawBegun) @@ -259,12 +270,14 @@ private GraphicsDeviceInformation DoPreparingDeviceSettings() #region IDisposable Members + /// public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } + /// protected virtual void Dispose(bool disposing) { if (!_disposed)