Added custom material example for metal and documented load_material

Author: birhburh

examples/custom_material.rs

@@ -26,6 +26,54 @@ void main() {
     gl_FragColor = test_color * texture2D(Texture, uv);
 }"#;
 
+pub const METAL: &str = r#"
+#include <metal_stdlib>
+using namespace metal;
+
+struct Vertex
+{
+    float3 position    [[attribute(0)]];
+    float2 texcoord    [[attribute(1)]];
+    float4 color0      [[attribute(2)]];
+};
+
+struct RasterizerData
+{
+    float4 position [[position]];
+    float4 color [[user(locn0)]];
+    float2 uv [[user(locn1)]];
+};
+
+// Uniforms should have Model, Projection, _Time in exact order for shader to work,
+// because they are laying in a single buffer
+struct Uniforms
+{
+    float4x4 Model;
+    float4x4 Projection;
+    float4 _Time;
+
+    float4 test_color;
+};
+
+vertex RasterizerData vertexShader(Vertex v [[stage_in]],
+                                   constant Uniforms& u [[buffer(0)]])
+{
+    RasterizerData out;
+
+    out.position = u.Projection * u.Model * float4(v.position, 1);
+    out.uv = v.texcoord;
+
+    return out;
+}
+
+fragment float4 fragmentShader(RasterizerData in [[stage_in]],
+                               constant Uniforms& u [[buffer(0)]],
+                               texture2d<float> Texture [[texture(0)]],
+                               sampler TextureSmplr [[sampler(0)]])
+{
+    return u.test_color * Texture.sample(TextureSmplr, in.uv);
+}"#;
+
 const FRAGMENT_WITH_ARRAY: &str = r#"#version 100
 varying lowp vec2 uv;
 
@@ -36,7 +84,70 @@ void main() {
     gl_FragColor = test_color[5] * texture2D(Texture, uv);
 }"#;
 
-#[macroquad::main("Shaders")]
+pub const METAL_WITH_ARRAY: &str = r#"#include <metal_stdlib>
+using namespace metal;
+
+struct Vertex
+{
+    float3 position    [[attribute(0)]];
+    float2 texcoord    [[attribute(1)]];
+    float4 color0      [[attribute(2)]];
+};
+
+struct RasterizerData
+{
+    float4 position [[position]];
+    float4 color [[user(locn0)]];
+    float2 uv [[user(locn1)]];
+};
+
+// Uniforms should have Model, Projection, _Time for material shaders to work
+struct Uniforms
+{
+    float4x4 Model;
+    float4x4 Projection;
+    float4 _Time;
+
+    float4 test_color[10];
+};
+
+vertex RasterizerData vertexShader(Vertex v [[stage_in]],
+                                   constant Uniforms& u [[buffer(0)]])
+{
+    RasterizerData out;
+
+    out.position = u.Projection * u.Model * float4(v.position, 1);
+    out.uv = v.texcoord;
+
+    return out;
+}
+
+fragment float4 fragmentShader(RasterizerData in [[stage_in]],
+                               constant Uniforms& u [[buffer(0)]],
+                               texture2d<float> Texture [[texture(0)]],
+                               sampler TextureSmplr [[sampler(0)]])
+{
+    return u.test_color[5] * Texture.sample(TextureSmplr, in.uv);
+}"#;
+
+fn window_conf() -> Conf {
+    let metal = std::env::args().nth(1).as_deref() == Some("metal");
+    let apple_gfx_api = if metal {
+        conf::AppleGfxApi::Metal
+    } else {
+        conf::AppleGfxApi::OpenGl
+    };
+    Conf {
+        window_title: "Shaders".to_owned(),
+        platform: conf::Platform {
+            apple_gfx_api,
+            ..Default::default()
+        },
+        ..Default::default()
+    }
+}
+
+#[macroquad::main(window_conf)]
 async fn main() {
     let pipeline_params = PipelineParams {
         color_blend: Some(BlendState::new(
@@ -47,10 +158,14 @@ async fn main() {
         ..Default::default()
     };
 
+    let ctx = unsafe { get_internal_gl().quad_context };
     let mat = load_material(
-        ShaderSource::Glsl {
-            vertex: VERTEX,
-            fragment: FRAGMENT,
+        match ctx.info().backend {
+            Backend::OpenGl => ShaderSource::Glsl {
+                vertex: VERTEX,
+                fragment: FRAGMENT,
+            },
+            Backend::Metal => ShaderSource::Msl { program: METAL },
         },
         MaterialParams {
             uniforms: vec![UniformDesc::new("test_color", UniformType::Float4)],
@@ -61,9 +176,14 @@ async fn main() {
     .unwrap();
 
     let mat_with_array = load_material(
-        ShaderSource::Glsl {
-            vertex: VERTEX,
-            fragment: FRAGMENT_WITH_ARRAY,
+        match ctx.info().backend {
+            Backend::OpenGl => ShaderSource::Glsl {
+                vertex: VERTEX,
+                fragment: FRAGMENT_WITH_ARRAY,
+            },
+            Backend::Metal => ShaderSource::Msl {
+                program: METAL_WITH_ARRAY,
+            },
         },
         MaterialParams {
             uniforms: vec![UniformDesc::array(

src/material.rs

@@ -60,6 +60,65 @@ pub struct MaterialParams {
     pub textures: Vec<String>,
 }
 
+/// Creates custom material
+///
+/// For OpenGL and Metal examples check examples/custom_material.rs.
+///
+/// # Default variables for OpenGL backend:
+/// ## Attributes (order doesn't matter, any could be skipped):
+/// ```glsl
+/// attribute vec3 position;
+/// attribute vec4 color0;
+/// attribute vec2 texcoord;
+/// ```
+/// ## Uniforms (order doesn't matter, any could be skipped):
+/// ```glsl
+/// uniform mat4 Model;
+/// uniform mat4 Projection;
+/// uniform float4 _Time;
+/// ```
+/// ## Textures (order doesn't matter, any could be skipped):
+/// ```glsl
+/// uniform sampler2D Texture;
+/// uniform sampler2D _ScreenTexture; // check examples/screen_texture.rs to see how it works
+/// ```
+///
+/// # Default variables for Metal backend:
+/// ## Attributes (order doesn't matter, any could be skipped, should have exact index in attribute()):
+/// ```msl
+/// struct Vertex
+/// {
+///     float3 position    [[attribute(0)]];
+///     float2 texcoord    [[attribute(1)]];
+///     float4 color0      [[attribute(2)]];
+/// };
+/// ```
+/// ## Uniforms (**order matters, all fields before needed one should present**):
+/// **All uniforms are in the same buffer, so order matters also for custom additional uniforms**
+/// ```msl
+/// struct Uniforms
+/// {
+///     float4x4 Model;
+///     float4x4 Projection;
+///     float4 _Time;
+///     ...
+///     additional uniforms
+/// };
+/// // same for vertexShader
+/// // Only buffer(0) is correct here
+/// fragment float4 fragmentShader(..., constant Uniforms& u [[buffer(0)]], ...) {...}
+/// ```
+/// ## Textures (order doesn't matter, any could be skipped, should have exact indices in `texture()` and `sampler()`):
+/// ```msl
+/// // same for vertexShader
+/// fragment float4 fragmentShader(...,
+///     texture2d<float> Texture [[texture(0)]],
+///     sampler TextureSmplr [[sampler(0)]],
+///     _ScreenTexture is not working for metal for now
+///     ...
+/// ) {...}
+/// ```
+///
 pub fn load_material(
     shader: crate::ShaderSource,
     params: MaterialParams,