Updated cubemap reflections example

model/cubemap/example.md

@@ -1,9 +1,31 @@
 ---
-tags: model
+tags: model, material, shader
 title: Cubemap Reflection
-brief: This example shows how to use a cubemap to draw environment reflections on a model.
+brief: Shows how to sample a cubemap in a model shader to create environment reflections.
 author: Defold Foundation
-scripts: cubemap.script, cubemap_model.fp, cubemap_model.vp
+scripts: cubemap_model.vp, cubemap_model.fp, orbit_camera.script
+thumbnail: thumbnail.webp
 ---
 
-This example contains a game object with a model component in the shape of the Defold logo. The model has a special `cubemap_model.material` which uses a cubemap sampler to calculate reflections on the model from the cubemap.
+The example renders the Defold logo with a custom material that reflects an environment cubemap. Drag or touch to orbit around the model and use the mouse wheel to zoom.
+
+## What You'll Learn
+
+- How to bind a cubemap texture to a model material sampler
+- How to compute world-space reflection vectors for environment mapping
+
+## Setup
+
+The collection contains a `logo` game object with an embedded Model component using `/example/assets/defold_logo.gltf`. Its material is `/example/cubemap_model.material`, and the material's `env_map` sampler is bound to `/example/assets/env.cubemap`.
+
+The `camera` game object contains a perspective Camera component and `orbit_camera.script`. The script is used only to move the camera around the logo from pointer and mouse wheel input.
+
+There is also an `info` game object with a GUI with a text to display controls on screen.
+
+![setup](setup.png)
+
+## How It Works
+
+`cubemap_model.vp` receives the model position, normal, and per-instance `mtx_world` attribute. It transforms the normal into world space, derives the camera world position from the view matrix, and calculates a reflection vector for each vertex.
+
+`cubemap_model.fp` samples the cubemap with that reflection vector. A small Fresnel term makes the logo edges more reflective, which makes the environment reflection easier to see while keeping the shader focused on cubemap sampling.

model/cubemap/example/cubemap.collection

@@ -10,10 +10,11 @@ embedded_instances {
   "  name: \\\"Material\\\"\\n"
   "  material: \\\"/example/cubemap_model.material\\\"\\n"
   "  textures {\\n"
-  "    sampler: \\\"envMap\\\"\\n"
+  "    sampler: \\\"env_map\\\"\\n"
   "    texture: \\\"/example/assets/env.cubemap\\\"\\n"
   "  }\\n"
   "}\\n"
+  "create_go_bones: false\\n"
   "\"\n"
   "}\n"
   ""
@@ -27,19 +28,28 @@ embedded_instances {
   id: "camera"
   data: "components {\n"
   "  id: \"main\"\n"
-  "  component: \"/example/cubemap.script\"\n"
+  "  component: \"/example/orbit_camera.script\"\n"
   "}\n"
   "embedded_components {\n"
   "  id: \"camera\"\n"
   "  type: \"camera\"\n"
   "  data: \"aspect_ratio: 1.0\\n"
   "fov: 0.7854\\n"
   "near_z: 1.0\\n"
-  "far_z: 100.0\\n"
+  "far_z: 50.0\\n"
+  "auto_aspect_ratio: 1\\n"
   "\"\n"
   "}\n"
   ""
   position {
     z: 10.0
   }
 }
+embedded_instances {
+  id: "info"
+  data: "components {\n"
+  "  id: \"info\"\n"
+  "  component: \"/example/info.gui\"\n"
+  "}\n"
+  ""
+}

model/cubemap/example/cubemap_model.fp

@@ -1,11 +1,30 @@
 #version 140
 
-in mediump vec3 vReflect;
-out vec4 out_FragColor;
+// These values are calculated per vertex in `cubemap_model.vp` and
+// interpolated for each fragment.
+in vec3 var_reflection;
+in float var_fresnel;
 
-uniform samplerCube envMap;
+// Output fragment color
+out vec4 out_frag_color;
+
+// Environment map
+// This sampler name must match the sampler in `cubemap_model.material` and
+// the texture binding in the Model component.
+uniform samplerCube env_map;
 
 void main()
 {
-	out_FragColor = texture(envMap, vReflect);
-}
+	// Normalize after interpolation, then sample the cubemap in that direction.
+	vec3 reflected_color = texture(env_map, normalize(var_reflection)).rgb;
+
+	// You can add a small base color so the logo still has shape in darker cubemap areas.
+	vec3 base_color = vec3(0.06, 0.08, 0.1);
+
+	// Fresnel makes shallow viewing angles more reflective, which helps show
+	// that the cubemap is responding to the model's surface direction.
+	float reflection_strength = mix(0.72, 1.0, var_fresnel);
+	vec3 color = mix(base_color, reflected_color, reflection_strength);
+
+	out_frag_color = vec4(color, 1.0);
+}

model/cubemap/example/cubemap_model.material

@@ -2,24 +2,20 @@ name: "cubemap_model"
 tags: "model"
 vertex_program: "/example/cubemap_model.vp"
 fragment_program: "/example/cubemap_model.fp"
+vertex_space: VERTEX_SPACE_LOCAL
 vertex_constants {
-  name: "view_proj"
-  type: CONSTANT_TYPE_VIEWPROJ
+  name: "mtx_view"
+  type: CONSTANT_TYPE_VIEW
 }
 vertex_constants {
-  name: "world"
-  type: CONSTANT_TYPE_WORLD
-}
-vertex_constants {
-  name: "cameraPosition"
-  type: CONSTANT_TYPE_USER
-  value {
-  }
+  name: "mtx_proj"
+  type: CONSTANT_TYPE_PROJECTION
 }
 samplers {
-  name: "envMap"
+  name: "env_map"
   wrap_u: WRAP_MODE_CLAMP_TO_EDGE
   wrap_v: WRAP_MODE_CLAMP_TO_EDGE
   filter_min: FILTER_MODE_MIN_LINEAR
   filter_mag: FILTER_MODE_MAG_LINEAR
+  max_anisotropy: 0.0
 }

model/cubemap/example/cubemap_model.vp

@@ -1,25 +1,63 @@
 #version 140
 
-uniform vs_uniforms {
-	mediump mat4 view_proj;
-	mediump mat4 world;
-	mediump mat4 normal_transform;
-	mediump mat4 world_view;
-	mediump vec4 cameraPosition;
+// Model components provide local vertex data. The material uses
+// `VERTEX_SPACE_LOCAL`, so the shader must transform positions itself.
+in vec4 position;
+in vec3 normal;
+
+// Defold automatically provides `mtx_world` as a per-instance attribute for
+// model materials in local vertex space. It is not listed as a material uniform.
+in mat4 mtx_world;
+
+// `mtx_view` and `mtx_proj` are vertex constants declared in `cubemap_model.material`.
+uniform general_vp
+{
+	mat4 mtx_view;
+	mat4 mtx_proj;
 };
 
-in mediump vec3 position;
-in mediump vec3 normal;
-in mediump vec2 texcoord0;
+// The fragment shader samples the cubemap with this reflected world direction.
+out vec3 var_reflection;
 
-out mediump vec3 vReflect;
+// The Fresnel value is used only to make grazing angles slightly brighter.
+out float var_fresnel;
+
+// Build a world-space normal matrix from `mtx_world`.
+// This is equivalent to transpose(inverse(mat3(mtx_world))) after normalize(),
+// but avoids a full matrix inverse in the shader.
+mat3 adjoint(mat4 m)
+{
+	return mat3(
+		cross(m[1].xyz, m[2].xyz),
+		cross(m[2].xyz, m[0].xyz),
+		cross(m[0].xyz, m[1].xyz)
+	);
+}
+
+// The cubemap reflection vector needs the camera position in world space.
+// Defold gives us the view matrix, so this converts it back to camera origin.
+vec3 camera_position_from_view(mat4 view)
+{
+	return -(transpose(mat3(view)) * view[3].xyz);
+}
 
 void main()
 {
-	vec4 worldP = world * vec4(position, 1.0);
-	gl_Position = view_proj * worldP;
-
-	vec3 worldNormal = normalize(normal);
-	vec3 cameraToVertex = normalize( worldP.xyz - cameraPosition.xyz );
-	vReflect = reflect( cameraToVertex, worldNormal );
+	// Move the vertex from model space to world space before projecting it.
+	vec4 world_position = mtx_world * vec4(position.xyz, 1.0);
+
+	// Transform the model normal into world space so it matches the cubemap.
+	vec3 world_normal = normalize(adjoint(mtx_world) * normal);
+
+	// Create the incident view direction used by GLSL `reflect()`.
+	vec3 camera_position = camera_position_from_view(mtx_view);
+	vec3 camera_to_vertex = normalize(world_position.xyz - camera_position);
+
+	// Reflect the view direction around the surface normal.
+	// The result points into the cubemap and is interpolated across the model surface.
+	var_reflection = reflect(camera_to_vertex, world_normal);
+	var_fresnel = pow(1.0 - max(dot(-camera_to_vertex, world_normal), 0.0), 4.0);
+
+	// Finish the model transform: world -> view -> projection.
+	gl_Position = mtx_proj * mtx_view * world_position;
 }

model/cubemap/example/info.gui

@@ -0,0 +1,22 @@
+fonts {
+  name: "always_on_top"
+  font: "/builtins/fonts/default.font"
+}
+nodes {
+  position {
+    x: 360.0
+    y: 680.0
+  }
+  size {
+    x: 200.0
+    y: 100.0
+  }
+  type: TYPE_TEXT
+  text: "Click/touch and move to rotate\n"
+  "Scroll to zoom"
+  font: "always_on_top"
+  id: "text"
+  inherit_alpha: true
+}
+material: "/builtins/materials/gui.material"
+adjust_reference: ADJUST_REFERENCE_PARENT