From 430faeb8ef9a5906af642a4a2be0eb6e878f812e Mon Sep 17 00:00:00 2001 From: gdkchan <gab.dark.100@gmail.com> Date: Tue, 31 Dec 2019 01:46:57 -0300 Subject: [PATCH] Add XML documentation to Ryujinx.Graphics.Gpu.Shader --- Ryujinx.Graphics.Gpu/Memory/MemoryManager.cs | 4 +- Ryujinx.Graphics.Gpu/Memory/PhysicalMemory.cs | 2 +- Ryujinx.Graphics.Gpu/Memory/RangeList.cs | 2 +- Ryujinx.Graphics.Gpu/Shader/CachedShader.cs | 20 +++- Ryujinx.Graphics.Gpu/Shader/ComputeShader.cs | 14 +++ Ryujinx.Graphics.Gpu/Shader/GraphicsShader.cs | 12 ++ .../Shader/ShaderAddresses.cs | 17 +++ Ryujinx.Graphics.Gpu/Shader/ShaderCache.cs | 104 +++++++++++++++++- Ryujinx.Graphics.Gpu/Shader/ShaderDumper.cs | 33 +++++- 9 files changed, 197 insertions(+), 11 deletions(-) diff --git a/Ryujinx.Graphics.Gpu/Memory/MemoryManager.cs b/Ryujinx.Graphics.Gpu/Memory/MemoryManager.cs index d4d9b48a..62ab0e47 100644 --- a/Ryujinx.Graphics.Gpu/Memory/MemoryManager.cs +++ b/Ryujinx.Graphics.Gpu/Memory/MemoryManager.cs @@ -44,7 +44,7 @@ namespace Ryujinx.Graphics.Gpu.Memory /// <param name="pa">CPU virtual address to map into</param> /// <param name="va">GPU virtual address to be mapped</param> /// <param name="size">Size in bytes of the mapping</param> - /// <returns>The GPU virtual address of the mapping</returns> + /// <returns>GPU virtual address of the mapping</returns> public ulong Map(ulong pa, ulong va, ulong size) { lock (_pageTable) @@ -117,7 +117,7 @@ namespace Ryujinx.Graphics.Gpu.Memory /// Reserves memory at a fixed GPU memory location. /// This prevents the reserved region from being used for memory allocation for map. /// </summary> - /// <param name="va">CPU virtual address to reserve</param> + /// <param name="va">GPU virtual address to reserve</param> /// <param name="size">Reservation size in bytes</param> /// <returns>GPU virtual address of the reservation, or an all ones mask in case of failure</returns> public ulong ReserveFixed(ulong va, ulong size) diff --git a/Ryujinx.Graphics.Gpu/Memory/PhysicalMemory.cs b/Ryujinx.Graphics.Gpu/Memory/PhysicalMemory.cs index 7a6b0963..71384df2 100644 --- a/Ryujinx.Graphics.Gpu/Memory/PhysicalMemory.cs +++ b/Ryujinx.Graphics.Gpu/Memory/PhysicalMemory.cs @@ -6,7 +6,7 @@ namespace Ryujinx.Graphics.Gpu.Memory /// <summary> /// Represents physical memory, accessible from the GPU. - /// This is actually working CPU virtual addresses, of memory mapped on the game process. + /// This is actually working CPU virtual addresses, of memory mapped on the application process. /// </summary> class PhysicalMemory { diff --git a/Ryujinx.Graphics.Gpu/Memory/RangeList.cs b/Ryujinx.Graphics.Gpu/Memory/RangeList.cs index 52bcf9b4..1d185e21 100644 --- a/Ryujinx.Graphics.Gpu/Memory/RangeList.cs +++ b/Ryujinx.Graphics.Gpu/Memory/RangeList.cs @@ -4,7 +4,7 @@ using System.Collections.Generic; namespace Ryujinx.Graphics.Gpu.Memory { /// <summary> - /// Lists of GPU resources with data on guest memory. + /// List of GPU resources with data on guest memory. /// </summary> /// <typeparam name="T">Type of the GPU resource</typeparam> class RangeList<T> where T : IRange<T> diff --git a/Ryujinx.Graphics.Gpu/Shader/CachedShader.cs b/Ryujinx.Graphics.Gpu/Shader/CachedShader.cs index 210d0720..362d149a 100644 --- a/Ryujinx.Graphics.Gpu/Shader/CachedShader.cs +++ b/Ryujinx.Graphics.Gpu/Shader/CachedShader.cs @@ -3,13 +3,31 @@ using Ryujinx.Graphics.Shader; namespace Ryujinx.Graphics.Gpu.Shader { + /// <summary> + /// Cached shader code for a single shader stage. + /// </summary> class CachedShader { + /// <summary> + /// Shader program containing translated code. + /// </summary> public ShaderProgram Program { get; } - public IShader Shader { get; set; } + /// <summary> + /// Host shader object. + /// </summary> + public IShader Shader { get; set; } + + /// <summary> + /// Maxwell binary shader code. + /// </summary> public int[] Code { get; } + /// <summary> + /// Creates a new instace of the cached shader. + /// </summary> + /// <param name="program">Shader program</param> + /// <param name="code">Maxwell binary shader code</param> public CachedShader(ShaderProgram program, int[] code) { Program = program; diff --git a/Ryujinx.Graphics.Gpu/Shader/ComputeShader.cs b/Ryujinx.Graphics.Gpu/Shader/ComputeShader.cs index 908b04b9..d7a701ea 100644 --- a/Ryujinx.Graphics.Gpu/Shader/ComputeShader.cs +++ b/Ryujinx.Graphics.Gpu/Shader/ComputeShader.cs @@ -2,12 +2,26 @@ using Ryujinx.Graphics.GAL; namespace Ryujinx.Graphics.Gpu.Shader { + /// <summary> + /// Cached compute shader code. + /// </summary> class ComputeShader { + /// <summary> + /// Host shader program object. + /// </summary> public IProgram HostProgram { get; set; } + /// <summary> + /// Cached shader. + /// </summary> public CachedShader Shader { get; } + /// <summary> + /// Creates a new instance of the compute shader. + /// </summary> + /// <param name="hostProgram">Host shader program</param> + /// <param name="shader">Cached shader</param> public ComputeShader(IProgram hostProgram, CachedShader shader) { HostProgram = hostProgram; diff --git a/Ryujinx.Graphics.Gpu/Shader/GraphicsShader.cs b/Ryujinx.Graphics.Gpu/Shader/GraphicsShader.cs index 7bdf68f7..14c8e5c2 100644 --- a/Ryujinx.Graphics.Gpu/Shader/GraphicsShader.cs +++ b/Ryujinx.Graphics.Gpu/Shader/GraphicsShader.cs @@ -2,12 +2,24 @@ using Ryujinx.Graphics.GAL; namespace Ryujinx.Graphics.Gpu.Shader { + /// <summary> + /// Cached graphics shader code for all stages. + /// </summary> class GraphicsShader { + /// <summary> + /// Host shader program object. + /// </summary> public IProgram HostProgram { get; set; } + /// <summary> + /// Compiled shader for each shader stage. + /// </summary> public CachedShader[] Shader { get; } + /// <summary> + /// Creates a new instance of cached graphics shader. + /// </summary> public GraphicsShader() { Shader = new CachedShader[5]; diff --git a/Ryujinx.Graphics.Gpu/Shader/ShaderAddresses.cs b/Ryujinx.Graphics.Gpu/Shader/ShaderAddresses.cs index c0a9162a..76ea3248 100644 --- a/Ryujinx.Graphics.Gpu/Shader/ShaderAddresses.cs +++ b/Ryujinx.Graphics.Gpu/Shader/ShaderAddresses.cs @@ -2,6 +2,9 @@ using System; namespace Ryujinx.Graphics.Gpu.Shader { + /// <summary> + /// Shader code addresses in memory for each shader stage. + /// </summary> struct ShaderAddresses : IEquatable<ShaderAddresses> { public ulong VertexA; @@ -11,11 +14,21 @@ namespace Ryujinx.Graphics.Gpu.Shader public ulong Geometry; public ulong Fragment; + /// <summary> + /// Check if the addresses are equal. + /// </summary> + /// <param name="other">Shader addresses structure to compare with</param> + /// <returns>True if they are equal, false otherwise</returns> public override bool Equals(object other) { return other is ShaderAddresses addresses && Equals(addresses); } + /// <summary> + /// Check if the addresses are equal. + /// </summary> + /// <param name="other">Shader addresses structure to compare with</param> + /// <returns>True if they are equal, false otherwise</returns> public bool Equals(ShaderAddresses other) { return VertexA == other.VertexA && @@ -26,6 +39,10 @@ namespace Ryujinx.Graphics.Gpu.Shader Fragment == other.Fragment; } + /// <summary> + /// Computes hash code from the addresses. + /// </summary> + /// <returns>Hash code</returns> public override int GetHashCode() { return HashCode.Combine(VertexA, Vertex, TessControl, TessEvaluation, Geometry, Fragment); diff --git a/Ryujinx.Graphics.Gpu/Shader/ShaderCache.cs b/Ryujinx.Graphics.Gpu/Shader/ShaderCache.cs index bd3229bd..b299da1a 100644 --- a/Ryujinx.Graphics.Gpu/Shader/ShaderCache.cs +++ b/Ryujinx.Graphics.Gpu/Shader/ShaderCache.cs @@ -11,6 +11,9 @@ namespace Ryujinx.Graphics.Gpu.Shader { using TextureDescriptor = Image.TextureDescriptor; + /// <summary> + /// Memory cache of shader code. + /// </summary> class ShaderCache { private const int MaxProgramSize = 0x100000; @@ -25,17 +28,31 @@ namespace Ryujinx.Graphics.Gpu.Shader private Dictionary<ShaderAddresses, List<GraphicsShader>> _gpPrograms; + /// <summary> + /// Creates a new instance of the shader cache. + /// </summary> + /// <param name="context">GPU context that the shader cache belongs to</param> public ShaderCache(GpuContext context) { _context = context; - _dumper = new ShaderDumper(context); + _dumper = new ShaderDumper(); _cpPrograms = new Dictionary<ulong, List<ComputeShader>>(); _gpPrograms = new Dictionary<ShaderAddresses, List<GraphicsShader>>(); } + /// <summary> + /// Gets a compute shader from the cache. + /// This automatically translates, compiles and adds the code to the cache if not present. + /// </summary> + /// <param name="gpuVa">GPU virtual address of the binary shader code</param> + /// <param name="sharedMemorySize">Shared memory size of the compute shader</param> + /// <param name="localSizeX">Local group size X of the computer shader</param> + /// <param name="localSizeY">Local group size Y of the computer shader</param> + /// <param name="localSizeZ">Local group size Z of the computer shader</param> + /// <returns>Compiled compute shader code</returns> public ComputeShader GetComputeShader(ulong gpuVa, int sharedMemorySize, int localSizeX, int localSizeY, int localSizeZ) { bool isCached = _cpPrograms.TryGetValue(gpuVa, out List<ComputeShader> list); @@ -73,6 +90,14 @@ namespace Ryujinx.Graphics.Gpu.Shader return cpShader; } + /// <summary> + /// Gets a graphics shader program from the shader cache. + /// This includes all the specified shader stages. + /// This automatically translates, compiles and adds the code to the cache if not present. + /// </summary> + /// <param name="state">Current GPU state</param> + /// <param name="addresses">Addresses of the shaders for each stage</param> + /// <returns>Compiled graphics shader code</returns> public GraphicsShader GetGraphicsShader(GpuState state, ShaderAddresses addresses) { bool isCached = _gpPrograms.TryGetValue(addresses, out List<GraphicsShader> list); @@ -138,11 +163,23 @@ namespace Ryujinx.Graphics.Gpu.Shader return gpShaders; } + /// <summary> + /// Checks if compute shader code in memory is different from the cached shader. + /// </summary> + /// <param name="cpShader">Cached compute shader</param> + /// <param name="gpuVa">GPU virtual address of the shader code in memory</param> + /// <returns>True if the code is different, false otherwise</returns> private bool IsShaderDifferent(ComputeShader cpShader, ulong gpuVa) { return IsShaderDifferent(cpShader.Shader, gpuVa); } + /// <summary> + /// Checks if graphics shader code from all stages in memory is different from the cached shaders. + /// </summary> + /// <param name="gpShaders">Cached graphics shaders</param> + /// <param name="addresses">GPU virtual addresses of all enabled shader stages</param> + /// <returns>True if the code is different, false otherwise</returns> private bool IsShaderDifferent(GraphicsShader gpShaders, ShaderAddresses addresses) { for (int stage = 0; stage < gpShaders.Shader.Length; stage++) @@ -174,6 +211,12 @@ namespace Ryujinx.Graphics.Gpu.Shader return false; } + /// <summary> + /// Checks if the code of the specified cached shader is different from the code in memory. + /// </summary> + /// <param name="shader">Cached shader to compare with</param> + /// <param name="gpuVa">GPU virtual address of the binary shader code</param> + /// <returns>True if the code is different, false otherwise</returns> private bool IsShaderDifferent(CachedShader shader, ulong gpuVa) { for (int index = 0; index < shader.Code.Length; index++) @@ -187,6 +230,15 @@ namespace Ryujinx.Graphics.Gpu.Shader return false; } + /// <summary> + /// Translates the binary Maxwell shader code to something that the host API accepts. + /// </summary> + /// <param name="gpuVa">GPU virtual address of the binary shader code</param> + /// <param name="sharedMemorySize">Shared memory size of the compute shader</param> + /// <param name="localSizeX">Local group size X of the computer shader</param> + /// <param name="localSizeY">Local group size Y of the computer shader</param> + /// <param name="localSizeZ">Local group size Z of the computer shader</param> + /// <returns>Compiled compute shader code</returns> private CachedShader TranslateComputeShader(ulong gpuVa, int sharedMemorySize, int localSizeX, int localSizeY, int localSizeZ) { if (gpuVa == 0) @@ -230,6 +282,15 @@ namespace Ryujinx.Graphics.Gpu.Shader return new CachedShader(program, codeCached); } + /// <summary> + /// Translates the binary Maxwell shader code to something that the host API accepts. + /// This will combine the "Vertex A" and "Vertex B" shader stages, if specified, into one shader. + /// </summary> + /// <param name="state">Current GPU state</param> + /// <param name="stage">Shader stage</param> + /// <param name="gpuVa">GPU virtual address of the shader code</param> + /// <param name="gpuVaA">Optional GPU virtual address of the "Vertex A" shader code</param> + /// <returns></returns> private CachedShader TranslateGraphicsShader(GpuState state, ShaderStage stage, ulong gpuVa, ulong gpuVaA = 0) { if (gpuVa == 0) @@ -301,6 +362,12 @@ namespace Ryujinx.Graphics.Gpu.Shader return new CachedShader(program, codeCached); } + /// <summary> + /// Performs backwards propagation of interpolation qualifiers or later shader stages input, + /// to ealier shader stages output. + /// This is required by older versions of OpenGL (pre-4.3). + /// </summary> + /// <param name="program">Graphics shader cached code</param> private void BackpropQualifiers(GraphicsShader program) { ShaderProgram fragmentShader = program.Shader[4].Program; @@ -334,6 +401,11 @@ namespace Ryujinx.Graphics.Gpu.Shader } } + /// <summary> + /// Gets the primitive topology for the current draw. + /// This is required by geometry shaders. + /// </summary> + /// <returns>Primitive topology</returns> private InputTopology GetPrimitiveTopology() { switch (_context.Methods.PrimitiveType) @@ -359,11 +431,29 @@ namespace Ryujinx.Graphics.Gpu.Shader return InputTopology.Points; } + /// <summary> + /// Check if the target of a given texture is texture buffer. + /// This is required as 1D textures and buffer textures shares the same sampler type on binary shader code, + /// but not on GLSL. + /// </summary> + /// <param name="state">Current GPU state</param> + /// <param name="stageIndex">Index of the shader stage</param> + /// <param name="index">Index of the texture (this is the shader "fake" handle)</param> + /// <returns>True if the texture is a buffer texture, false otherwise</returns> private bool QueryIsTextureBuffer(GpuState state, int stageIndex, int index) { return GetTextureDescriptor(state, stageIndex, index).UnpackTextureTarget() == TextureTarget.TextureBuffer; } + /// <summary> + /// Check if the target of a given texture is texture rectangle. + /// This is required as 2D textures and rectangle textures shares the same sampler type on binary shader code, + /// but not on GLSL. + /// </summary> + /// <param name="state">Current GPU state</param> + /// <param name="stageIndex">Index of the shader stage</param> + /// <param name="index">Index of the texture (this is the shader "fake" handle)</param> + /// <returns>True if the texture is a rectangle texture, false otherwise</returns> private bool QueryIsTextureRectangle(GpuState state, int stageIndex, int index) { var descriptor = GetTextureDescriptor(state, stageIndex, index); @@ -376,11 +466,23 @@ namespace Ryujinx.Graphics.Gpu.Shader return !descriptor.UnpackTextureCoordNormalized() && is2DTexture; } + /// <summary> + /// Gets the texture descriptor for a given texture on the pool. + /// </summary> + /// <param name="state">Current GPU state</param> + /// <param name="stageIndex">Index of the shader stage</param> + /// <param name="index">Index of the texture (this is the shader "fake" handle)</param> + /// <returns>Texture descriptor</returns> private TextureDescriptor GetTextureDescriptor(GpuState state, int stageIndex, int index) { return _context.Methods.TextureManager.GetGraphicsTextureDescriptor(state, stageIndex, index); } + /// <summary> + /// Returns information required by both compute and graphics shader compilation. + /// </summary> + /// <param name="info">Information queried</param> + /// <returns>Requested information</returns> private int QueryInfoCommon(QueryInfoName info) { switch (info) diff --git a/Ryujinx.Graphics.Gpu/Shader/ShaderDumper.cs b/Ryujinx.Graphics.Gpu/Shader/ShaderDumper.cs index 04ad645b..3be75564 100644 --- a/Ryujinx.Graphics.Gpu/Shader/ShaderDumper.cs +++ b/Ryujinx.Graphics.Gpu/Shader/ShaderDumper.cs @@ -4,23 +4,29 @@ using System.IO; namespace Ryujinx.Graphics.Gpu.Shader { + /// <summary> + /// Shader dumper, writes binary shader code to disk. + /// </summary> class ShaderDumper { - private GpuContext _context; - private string _runtimeDir; private string _dumpPath; private int _dumpIndex; public int CurrentDumpIndex => _dumpIndex; - public ShaderDumper(GpuContext context) + public ShaderDumper() { - _context = context; - _dumpIndex = 1; } + /// <summary> + /// Dumps shader code to disk. + /// </summary> + /// <param name="code">Code to be dumped</param> + /// <param name="compute">True for compute shader code, false for graphics shader code</param> + /// <param name="fullPath">Output path for the shader code with header included</param> + /// <param name="codePath">Output path for the shader code without header</param> public void Dump(Span<byte> code, bool compute, out string fullPath, out string codePath) { _dumpPath = GraphicsConfig.ShadersDumpPath; @@ -68,16 +74,28 @@ namespace Ryujinx.Graphics.Gpu.Shader } } + /// <summary> + /// Returns the output directory for shader code with header. + /// </summary> + /// <returns>Directory path</returns> private string FullDir() { return CreateAndReturn(Path.Combine(DumpDir(), "Full")); } + /// <summary> + /// Returns the output directory for shader code without header. + /// </summary> + /// <returns>Directory path</returns> private string CodeDir() { return CreateAndReturn(Path.Combine(DumpDir(), "Code")); } + /// <summary> + /// Returns the full output directory for the current shader dump. + /// </summary> + /// <returns>Directory path</returns> private string DumpDir() { if (string.IsNullOrEmpty(_runtimeDir)) @@ -98,6 +116,11 @@ namespace Ryujinx.Graphics.Gpu.Shader return _runtimeDir; } + /// <summary> + /// Creates a new specified directory if needed. + /// </summary> + /// <param name="dir">The directory to create</param> + /// <returns>The same directory passed to the method</returns> private static string CreateAndReturn(string dir) { Directory.CreateDirectory(dir);