From e71c6cc8fc3139d10fb2ffff7cbf697df7f4b13a Mon Sep 17 00:00:00 2001
From: Isaac Marovitz <isaacryu@icloud.com>
Date: Mon, 9 Oct 2023 15:02:39 -0400
Subject: [PATCH] MSL Binding Model description

Might need tweaks/adjustments
---
 .../CodeGen/Msl/Declarations.cs               | 29 +++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/src/Ryujinx.Graphics.Shader/CodeGen/Msl/Declarations.cs b/src/Ryujinx.Graphics.Shader/CodeGen/Msl/Declarations.cs
index c7080b686b..9b43ba1dc1 100644
--- a/src/Ryujinx.Graphics.Shader/CodeGen/Msl/Declarations.cs
+++ b/src/Ryujinx.Graphics.Shader/CodeGen/Msl/Declarations.cs
@@ -9,6 +9,35 @@ namespace Ryujinx.Graphics.Shader.CodeGen.Msl
 {
     static class Declarations
     {
+        /*
+         * Description of MSL Binding Strategy
+         *
+         * There are a few fundamental differences between how GLSL and MSL handle I/O.
+         * This comment will set out to describe the reasons why things are done certain ways
+         * and to describe the overall binding model that we're striving for here.
+         *
+         * Main I/O Structs
+         *
+         * Each stage will have a main input and output struct labeled as [Stage][In/Out], i.e VertexIn.
+         * Every attribute within these structs will be labeled with an [[attribute(n)]] property,
+         * and the overall struct will be labeled with [[stage_in]] for input structs, and defined as the
+         * output type of the main shader function for the output struct. This struct also contains special
+         * attribute-based properties like [[position]], therefore these are not confined to 'user-defined' variables.
+         *
+         * Samplers & Textures
+         *
+         * Metal does not have a combined image sampler like sampler2D in GLSL, as a result we need to bind
+         * an individual texture and a sampler object for each instance of a combined image sampler.
+         * As a result, the binding indices of straight up textures (i.e. without a sampler) start
+         * after the last sampler/texture pair.
+         *
+         * Uniforms
+         *
+         * MSL does not have a concept of uniforms comparable to that of GLSL. As a result, instead of
+         * being declared outside of any function body, uniforms are part of the function signature in MSL.
+         * This applies to anything bound to the shader not included in the main I/O structs.
+         */
+
         public static void Declare(CodeGenContext context, StructuredProgramInfo info)
         {
             context.AppendLine("#include <metal_stdlib>");