Let’s start with a simple (though contrived) example. I’m writing some code that depends on the go-github library to interact with the GitHub API.

package before

import (
	"context"
	"fmt"

	"github.com/google/go-github/v47/github"
)

type obj struct {
	user string
	gh   *github.OrganizationsService
}

func New(user string) obj {
	return obj{
		user: user,
		gh:   github.NewClient(nil).Organizations,
	}
}

func (m *obj) CountOrganizations(ctx context.Context) (int, error) {
	orgs, _, err := m.gh.List(ctx, m.user, nil)
	if err != nil {
		return 0, fmt.Errorf("couldn't list organizations: %w", err)
	}
	return len(orgs), nil
}

func (m *obj) IsMemberOf(ctx context.Context, org string) (bool, error) {
	result, _, err := m.gh.IsMember(ctx, org, m.user)
	if err != nil {
		return false, fmt.Errorf("couldn't call IsMember: %w", err)
	}
	return result, nil
}

How do you test this? github.OrganizationsService is a struct type, so we’re required to have a direct instance of it to pass type checking. In many cases, this will force your tests to make network calls. Usually, you can pass http.Client and override its behavior, but that gets messy fast.

Setup

The key to testing this behavior is to depend on an interface type instead of the struct. Go makes this easy, which you may not know if you’re used to other languages. In Go, an interface describes behavior that both your code or dependency code can implement. This feature means we can define an interface in our code that github.OrganizationService implements and the compiler will recognize it.

type githubOrganizations interface {
}

type obj struct {
	user string
	gh   githubOrganizations
}

I usually start with an empty interface and add methods as needed. Doing this helps keep my interface as clean as possible, which makes understanding code when refactoring or changing dependencies later easier.

Swapping *github.OrganizationsService for githubOrganizations works because all structs conform to the empty interface. However, I now see errors wherever I use .gh: m.gh.List undefined (type githubOrganizations has no field or method List).

We need to add each of the undefined methods to the interface. If I’m too lazy to look at the docs, I’ll temporarily swap githubOrganizations back to *github.OrganizationsService, jump to the definition of the previously undefined method and port it over.

type githubOrganizations interface {
	List(ctx context.Context, user string, opts *github.ListOptions) ([]*github.Organization, *github.Response, error)
	IsMember(ctx context.Context, org, user string) (bool, *github.Response, error)
}

Writing a test

Now let’s use this interface to write a test verifying CountOrganizations works as expected.

func TestCountOrganizations(t *testing.T) {
	obj := obj{
		gh: mockGHList{},
	}

	c, err := obj.CountOrganizations(context.Background())
	if err != nil {
		t.Fatal(err)
	}
	if c != 3 {
		t.Fatalf("unexpected number of organizations: %d", c)
	}
}

Here’s the real magic: mockGHList is a struct that embeds a pointer to github.OrganizationsService, which we originally depended on.

type mockGHList struct {
	*github.OrganizationsService
}

Go pointer semantics and struct embedding rules mean all methods of *github.OrganizationsService can be called on mockGHList, even when the embedded value is nil. This allows us to run the test without compilation issues, but because github.OrganizationService is nil, the test panics.

--- FAIL: TestCountOrganizations (0.00s)
...
github.com/google/go-github/v47/github.(*OrganizationsService).List

A nil pointer was found when trying to call .List on the nil *github.OrganizationsService. Go struct embedding rules mean that methods defined on the mockGHList object override those on the nested *github.OrganizationsService object. This rule lets us write our mock method.

func (mockGHList) List(context.Context, string, *github.ListOptions) ([]*github.Organization, *github.Response, error) {
	return []*github.Organization{{}, {}, {}}, nil, nil
}

Rerun the test, and it passes!

--- PASS: TestCountOrganizations (0.00s)

Benefits

Single-use, minimal mocks

By wrapping the original struct, we only need to implement the methods our tests directly depend on. This encourages single-use, minimal mock objects instead of manually maintaining large shared mocks.

Any hardcoded mock codifies its expectations of how specific scenarios behave, usually the first tests it’s used in. Those expectations make it harder to use for new tests. As the codebase grows, it either doesn’t thoroughly test new behavior or combinatorially increases in complexity (by introducing [boolean flags](https://martinfowler.com/bliki/FlagArgument.html, for example). At some point, the mock deserves its own tests to track what it’s doing.

Fail-by-default

This pattern fails when executed code makes unexpected method calls, which can help catch accidental changes.

Mocking libraries

I’ve also successfully used this pattern with third-party mocking libraries.

Here’s an example of use with "github.com/stretchr/testify/mock".

type mockGHIsMember struct {
	mock.Mock
	*github.OrganizationsService
}

func (m *mockGHIsMember) IsMember(ctx context.Context, org, user string) (bool, *github.Response, error) {
	args := m.Called(ctx, org, user)
	return args.Bool(0), args.Get(1).(*github.Response), args.Error(2)
}

func TestIsMember(t *testing.T) {
	gh := mockGHIsMember{}
	obj := obj{
		user: "apexskier",
		gh:   &gh,
	}

	gh.On("IsMember", mock.MatchedBy(func(context.Context) bool { return true }), "org", obj.user).Return(true, (*github.Response)(nil), nil)

	result, err := obj.IsMemberOf(context.Background(), "org")
	require.NoError(t, err)
	assert.True(t, result)
}

I still only need to mock the method being called.

Caveats

• Defining an interface does not work when using struct fields since interfaces can only declare methods.
• Auto-complete won’t show other methods available on the original struct type. https://pkg.go.dev is your friend, or you can manually declare a variable of the original type and use auto-complete on that.

You can view the code from this post at https://github.com/apexskier/go-struct-mocking-demo/.

One of my frequent use cases is iteration over a collection of varied objects. A type union allows me to avoid complicated merging and ordering logic and use simple conditional logic within the iteration body. It’s also used commonly in APIs I interact with, where a single resource can produce different but similar things, or I want to reduce ambiguity between conditional fields.

Type unions can be a stronger pattern than inheritance. In class-based inheritance, the possible set of types is unbounded, while type unions have an explicit set known at compile time. In languages like TypeScript (and Swift, as we’ll see), sub-types of a type union can be unrelated and have distinct inheritance chains.

In other languages

Type unions are simple in weakly typed languages like JavaScript or Python¹ since a variable can contain any value. Strongly typed languages take different approaches to support them.

TypeScript

TypeScript has first-class support with union types. Type narrowing is done with type predicates and custom functions.

interface Rabbit {
	name: string;
	eat(food: Carrot): void;
}
class Dog {
	name: string;
	pet() {}
}
interface Turtle {
	name: "turtle"
}

type Pet = Rabbit | Dog | Turtle

function whatIsIt(pet: Pet) {
	if (typeof pet == "string") {
		return "turtle"
	} else if (pet instanceof Dog) {
		pet.pet()
		return "dog"
	} else {
		return "rabbit"
	}
}

TypeScript is nice because it automatically casts the inspected variable’s type: within the conditional blocks, pet assumes the narrowed type. TypeScript automatically infers common attributes of the sub-types, allowing access to the common name property (pet.name).

Kotlin

Kotlin supports type unions with sealed classes. Type narrowing is done with when expressions.

sealed class Pet()
data class Rabbit(
	val name: String,
	val carrot: Double
) : Pet() {
	fun eat(food: Carrot) {}
}
class Dog(val name: String) : Pet() {
	fun pet() {}
}
object Turtle : Pet() {
	val name: String = "turtle"
}

fun whatIsIt(pet: Pet): String =
	when (pet) {
		is Rabbit -> "rabbit"
		is Dog -> {
			pet.pet()
			"dog"
		}
		is Turtle -> "turtle"
	}

Like TypeScript, variable types are automatically narrowed. Kotlin does not automatically infer common attributes, but they can be defined on the base sealed class, following standard inheritance patterns.

In Swift

The core construct for a type union in Swift is an enumeration with associated values. Type narrowing is done with case statements.

protocol Rabbit {
	var name: String { get }
	func eat(food: Carrot)
}
struct Dog {
	var name: String
	func pet() {}
}
typealias Turtle = String

enum Pet {
	case rabbit(Rabbit)
	case dog(Dog)
	case turtle(Turtle)
}

func whatIsIt(pet: Pet) -> String {
	switch pet {
	case .rabbit:
		return "rabbit"
	case .dog(let dog):
		dog.pet()
		return "dog"
	case .turtle:
		return "turtle"
	}
}

Notice that to get a variable of the narrowed type, a new variable is directly defined within the case expression (let dog).

A more concise form of type narrowing is also possible within an if statement².

if case .rabbit(let rabbit) = pet {
	// ...
}

The main downside to Swift’s form of type unions is that the value is nested within another. It’s not possible to directly use attributes on a Pet variable. To work around that, you need to define accessors on the enum itself³.

enum Pet {
	case rabbit(Rabbit)
	case dog(Dog)
	case turtle(Turtle)
	
	var name: String {
		switch self {
		case .rabbit(let rabbit):
			return rabbit.name
		case .dog(let dog):
			return dog.name
		case .turtle:
			return turtle
		}
	}
}

func example(pet: Pet) {
	pet.name
}

If the different sub-types share a protocol, you can define a single accessor to access the protocol.

protocol Mammal {
	var furColor: String { get }
}

enum Pet {
	case rabbit(Rabbit)
	case dog(Dog)
	case turtle(Turtle)
	
	var mammal: Mammal? {
		switch self {
		case .rabbit(let mammal as Mammal), .dog(let mammal as Mammal):
			return mammal
		case .turtle:
			return nil
		}
	}
}

func example(pet: Pet) {
	pet.mammal?.furColor
}

Taking this further, if all sub-types share a protocol, you can extend the enum itself from that protocol and delegate to that accessor.

protocol Animal {
	func sleep()
}

enum Pet: Animal {
	case rabbit(Rabbit)
	case dog(Dog)
	case turtle(Turtle)
	
	private var animal: Animal {
		switch self {
		case .rabbit(let animal as Animal),
			 .dog(let animal as Animal),
			 .turtle(let animal as Animal):
			return animal
		}
	}
	
	func sleep() {
		animal.sleep()
	}
}

func example(pet: Pet) {
	pet.sleep()
}

I find type unions significantly simplify my code and prevent mistakes by strengthening my type semantics. I hope this helps you out as well.

But maybe you don’t want to disable that nice physics interaction and want to have some fun with it instead. The goal here is to use css to add some sort of “hidden” content in the background of the site that’s only visible when over-scrolling.

By default, there are already two elements to play with: <html> and <body>. The first thing to understand is the sizing of these elements. Both element’s intrinsic content size is that of the containing content, but the <html> element is special, since its background takes up the full window size.

First, I want to make sure the <body> always covers the full content, so I don’t have anything in the background of the <html> peeking out at the bottom. I also need to make sure my layout doesn’t have any margins collapsing outside of the body, which in this demo I’ll do by making my body flex.

body {
	min-height: 100vh; /* full height */
	display: flex; /* optional - prevents margin collapse */
}

With a background color on the <html> element it’s visible when I overscroll. However, this is “fake” content on desktop browsers—the html is still scrolling so its contents aren’t shown (for example, a background image).

There are a couple of approaches I want to try to get content in there.

1. Don’t scroll the html - scroll the body instead

Unfortunately (at least in the desktop browsers I tested) this doesn’t work as I want. The only element that allows scrolling outside of its content is the <html> tag, so the behavior is the same as if I set overscroll-behavior: none.

html {
	overflow: hidden;
}

body {
	overflow: scroll;
	height: 100vh;
	overscroll-behavior: contain;
}

2. Add fake fixed elements that don’t scroll

I can use some trusty pseudo elements to add content, right?

html::before {
	z-index: 0;
	content: "";
	width: 100px;
	height: 100px;
	right: 0;
	background-color: red;
	position: fixed;
}

body::before {
	z-index: 0;
	content: "";
	width: 100px;
	height: 100px;
	background-color: blue;
	position: fixed;
}

body {
	z-index: 2;
	background-color: white;
}

Well, not really. On desktop, even position: fixed and position: sticky won’t scroll into the overflow area, just like a background-image of <html>. Another issue is that html pseudo elements display above the background of the <body>. Generally, a pseudo element follows the standard stacking context: body { background-color: white } should cover pseudo elements of <html> the same as it covers <html>.

However, this confirms that iOS doesn’t scroll fixed content when overscrolling. The body background issue persists though.

3. Add a wrapper element

Now the the DOM gets a little messy. We can introduce a wrapper element (instead of using <body>) to cover the full document with a non-opaque background color.

#wrapper {
	min-height: 100vh;
	min-width: 100vw;
	background-color: white;
}

<html>
	<body>
		<div id="wrapper"><!-- content --></div>
	</body>
</html>

And we finally have a hidden background element!

html::before {
	z-index: -1;
	position: fixed;
	height: 100vh;
	width: 100vw;
	content: "";
}

However, the browser support is pretty limited. As discovered above, desktop browsers scroll fixed elements during overscroll, meaning they’re not “revealed” like I want. In iOS Safari, however, it’s a pretty nice effect.

Unfortunately, there’s some glitchy behavior on desktop Safari where the background texture shows through un-rendered content.

Bonus!

We can use a hidden element and position: sticky to emulate snapchat’s pull-to-refresh ghost animation with pure CSS.

Try it here

3D objects with movement

If you haven’t already, go and read the first tutorial in this series. This tutorial will expand on the XML file from the first tutorial. The javascript and html are exactly the same.

The XML file is the only one that will change. This example will include a rotating cube and a sphere circling around it.

Elements needed

If you’ll remember, there are several things needed in our XML file. For this one we will need…

• Two <mesh>s composed of…
  • <positions>,
  • <normals>,
  • <uv1> and
  • <faces>,
• Two <material>s,
• A <camera> and
• A <scene> composed of…
  • Two <object>s
  • Two <light>s.

Meshes

We need to define two meshes for two separate objects in the scene: a cube and a sphere. I’ll go into a little more detail on making them in this tutorial compared to the last one.

Cube

<mesh id="cube">
</mesh>

The cube is composed of six sides. Each side is made of two flat triangles (like the one from the last tutorial). This will make a total of 36 corners or 36 coordinates in the <positions> element of the <mesh>, 36 coordinates in the <normals> element of the <mesh> and 36 numbers in the <faces> element of the <mesh>.

I’ll start off with the <positions> element. Each of the 36 corners will need an x, y, z coordinate. Each face of the cube will have be made of two triangles composed of 6 coordinates.

For the top face, a flat square, we will need…

  1, 1, 1,   // right 1 unit, forward 1 unit, up 1 unit
 -1, 1, 1,   // left  1 unit, forward 1 unit, up 1 unit
  1,-1, 1,   // right 1 unit, back    1 unit, up 1 unit
 -1, 1, 1,   // left  1 unit, forward 1 unit, up 1 unit
 -1,-1, 1,   // left  1 unit, back    1 unit, up 1 unit
  1,-1, 1... // right 1 unit, back    1 unit, up 1 unit

Now we have the <normals> for the top face. Each line is an x, y, z coordinate and defines which direction the light is reflected towards. A good rule of thumb (at least for cubes and flat faces) is that the normal for each corner of one face is +1 at the axis that all corners on the face are equal at. For the top face, each corner of the face is +1 at the z axis, so each normal is 0, 0, 1. The light is reflected up (to the z axis) for each corner and the space in between corners.

0, 0, 1,
0, 0, 1,
0, 0, 1,
0, 0, 1,
0, 0, 1,
0, 0, 1...

Since our example will not have images associated with objects and because all of the corners are defined separately, we don’t need a <uv1> section or a <faces> section. See another tutorial to learn about defining multiple corners with the same position element.

Lets build the rest of the <positions> and <normals> elements.

<positions>
    /* back */
     1,  1, 1,
     1,  1, -1,
    -1,  1, -1,
     1,  1, 1,
    -1,  1, -1,
    -1,  1, 1,

    /* left */
    -1, -1, -1,
    -1, -1, 1,
    -1,  1, 1,
    -1, -1, -1,
    -1,  1, 1,
    -1,  1, -1,

    /* front */
     1, -1, -1,
     1, -1, 1,
    -1, -1, -1,
     1, -1, 1,
    -1, -1, 1,
    -1, -1, -1,

    /* right */
     1,  1, -1,
     1,  1, 1,
     1, -1, -1,
     1,  1, 1,
     1, -1, 1,
     1, -1, -1,

    /* top */
     1,  1, 1,
    -1,  1, 1,
     1, -1, 1,
    -1,  1, 1,
    -1, -1, 1,
     1, -1, 1,

    /* bottom */
     1,  1, -1,
     1, -1, -1,
    -1, -1, -1,
     1,  1, -1,
    -1, -1, -1,
    -1,  1, -1
</positions>
<normals>
    /* back */
    0, 1, 0,
    0, 1, 0,
    0, 1, 0,
    0, 1, 0,
    0, 1, 0,
    0, 1, 0,

    /* left */
    -1, 0, 0,
    -1, 0, 0,
    -1, 0, 0,
    -1, 0, 0,
    -1, 0, 0,
    -1, 0, 0,

    /* front */
    0, -1, 0,
    0, -1, 0,
    0, -1, 0,
    0, -1, 0,
    0, -1, 0,
    0, -1, 0,

    /* right */
    1, 0, 0,
    1, 0, 0,
    1, 0, 0,
    1, 0, 0,
    1, 0, 0,
    1, 0, 0,

    /* top */
    0, 0, 1,
    0, 0, 1,
    0, 0, 1,
    0, 0, 1,
    0, 0, 1,
    0, 0, 1,

    /* bottom */
    0, 0,-1,
    0, 0,-1,
    0, 0,-1,
    0, 0,-1,
    0, 0,-1,
    0, 0,-1
</normals>

*don’t include comments in your XML file, they’re just here to help clear things up.

There’s the mesh for the cube!

Now we can define the material for the cube. This is pretty easy and no different than the last tutorial, an id, the specular value, and a color (this time, blue).

<material id="cubeMat" specular="1" color="#0088bb" />

Sphere

Now we will make the sphere. GLGE doesn’t have a very good way of dealing with spheres, so it has to be defined in the same way as the cube. The sphere in this example uses 1260 corners. I won’t walk you through that, because I haven’t made one manually myself, I’ve just copied the code from other examples. You can click here to see the code I’m using if you really want to.

For the sphere material, I’m going to make it red, and a bit less shiny.

<material id="sphereMat" specular="0.5" color="#cc0000" />

Animation

There are two ways to animate objects in GLGE. Animation can be defined in the javascript or the XML file. Usually animations are defined in the XML file and manipulated in the javascript file. For example, there could be an animation for a character walking and an animation for a character jumping (both in the XML file) and they could be switched via javascript. In this example, I’m only using the XML file.

Cube spin

I want the cube to rotate on the y and z axises.

First, I define this animation in an <animation_vector>. An <animation_vector> contains and id and the number of frames. These frames contribute to the speed of the animation (more on this later) and determine how we set keyframes.

<animation_vector id="spin" frames="240">

</animation_vector>

Inside the <animation_vector> we can set the attribute changes that will occur. To do this we add an <animation_curve> for each changing attribute.

So, we first add an <animation_curve> that changes the rotation around the y axis.

<animation_curve channel="RotY">

</animation_curve>

Inside this, we add the keyframes by adding <linear_point>s. Each has a x value that sets what frame it happens on, and a y value that sets the attribute value on that frame. So, in this example, at 0 frames in the animation (remember, the animation lasts 240 frames) the rotation on the y value is 0 radians, then it increases to 6.282 radians (about 360 degrees) on the 240th frame.

<linear_point x="0" y="0" />
<linear_point x="240" y="6.282" />

I also want it to rotate around the z axis, so we’ll add another <animation_curve> inside the <animation_vector>. It’s almost exaclty the same, only the <animation_curve>’s channel is set to the z axis.

<animation_curve channel="RotZ">
    <linear_point x="0" y="0" />
    <linear_point x="240" y="6.282" />
</animation_curve>

So here’s the final code for the sphere’s animation.

<animation_vector id="spin" frames="240">
    <animation_curve channel="RotY">
        <linear_point x="0" y="0" />
        <linear_point x="240" y="6.282" />
    </animation_curve>
    <animation_curve channel="RotZ">
        <linear_point x="0" y="0" />
        <linear_point x="240" y="6.282" />
    </animation_curve>
</animation_vector>

Sphere circling

I want the sphere to circle around the cube (or circling around the z axis. I could set an x and y location attribute for each frame, but there’s a much more efficient way to do this.

What we really want to do is move the sphere out 3 units, then rotate the whole system it’s on. Imagine holding a broom by the handle and swinging it around in a circle. The sphere is the broom’s end, and it is rotating around you, the z axis.

To do this, we need to introduce a new element into the XML file, a <group>. Then we can apply the animation to the group. I’ll go over the animation quickly, since it is very simple, then move onto the <object>s and <group>s. The only difference in this animation is that it has a total of 480 frames, rather than 240. This will make it take two times longer than the cube’s animation.

<animation_vector id="circle" frames="480">
    <animation_curve channel="RotZ">
        <linear_point x="0" y="0" />
        <linear_point x="480" y="6.282" />
    </animation_curve>
</animation_vector>

The rest (including groups)

Next we need to add a camera (see the previous tutorial for more info).

<camera id="mainCamera" />

and make a scene, with a light in it (again, see the previous tutorial for more info).

<scene id="mainScene" camera="#mainCamera" ambient_color="#fff">
    <light id="mainlight" loc_x="10" loc_y="15" loc_z="10" rot_x="-1.3" color="#fff" type="L_POINT" />
</scene>

Now we’ll add the cube. It has an id, references the mesh set up earlier, the material set up earlier, has some location and rotation attributes, and some new attributes. The first new attribute is the frame rate. This sets how many frames per second is applied to the animation. So, a frame rate of 60 means that an animation with a length of 240 will take (240 / 60 = 4) 4 seconds to complete and an animation with a length 480 will take 8 seconds to complete.

<object id="cube" mesh="#cube" material="#cubeMat" frame_rate="60" animation="#spin" loc_z="-10" rot_y="1" rot_x="1" />

Groups

Well, one group.

I want to do two things separately to the sphere, so I need to surround it with a group (sort of like adding a container element for extra css).

The group is moved down 10 units (same level as the cube) with a location attribute, and has the #circle animation applied to it. Inside the group is the sphere object moved out 3. It also has, the mesh defined above, material defined above, and scale attributes that make it 80% of the original size.

<group id="sphereGroup" animation="#circle" frame_rate="60" loc_z="-10">
    <object id="sphere" mesh="#sphere" material="#sphereMat" loc_x="3" scale_x="0.8" scale_y="0.8" scale_z="0.8" />
</group>

Woohoo! We’re done with the XML file for this tutorial. Here’s the whole thing.

<?xml version="1.0"?>
<glge>

    <mesh id="cube">
        /* cube mesh code */
    </mesh>

    <mesh id="sphere">
        /* sphere mesh code */
    </mesh>

    <material id="cubeMat" specular="1" color="#0088bb" />
    <material id="sphereMat" specular="0.5" color="#cc0000" />

    <animation_vector id="spin" frames="240">
        <animation_curve channel="RotY">
            <linear_point x="0" y="0" />
            <linear_point x="240" y="6.282" />
        </animation_curve>
        <animation_curve channel="RotZ">
            <linear_point x="0" y="0" />
            <linear_point x="240" y="6.282" />
        </animation_curve>
    </animation_vector>

    <animation_vector id="circle" frames="480">
        <animation_curve channel="RotZ">
            <linear_point x="0" y="0" />
            <linear_point x="480" y="6.282" />
        </animation_curve>
    </animation_vector>

    <camera id="mainCamera" />

    <scene id="mainScene" camera="#mainCamera" ambient_color="#fff">
        <group id="sphereGroup" animation="#circle" frame_rate="60" loc_z="-10">
            <object id="sphere" mesh="#sphere" material="#sphereMat" loc_x="3" scale_x="0.8" scale_y="0.8" scale_z="0.8" />
        </group>
        <object id="cube" mesh="#cube" material="#cubeMat" frame_rate="60" animation="#spin" loc_z="-10" rot_y="1" rot_x="1" />
        <light id="mainlight" loc_x="10" loc_y="15" loc_z="10" rot_x="-1.3" color="#fff" type="L_POINT" />
    </scene>

</glge>

Javascript

Last thing to do to make the animation work is to modify our javascript file a bit. If you use the javascript from the previous tutorial, it will render one frame of the animation and no more than that. Let’s look at the javascript for a static scene first.

var canvasElement = document.getElementById("canvas");
var doc = new GLGE.Document();

doc.load("tutorial2.xml");

doc.onLoad = function() {
    var renderer = new GLGE.Renderer(canvasElement);
    var scene = new GLGE.Scene();
    scene = doc.getElement("mainScene");
    renderer.setScene(scene);
    renderer.render();
}

The line we need to look at is here.

renderer.render();

This renders the scene once.

We need to set it to render over and over again with a setInterval() function. GLGE has logic that slows the animation down, so you can set it to render every 1 millisecond.

setInterval(function(){
    renderer.render();
}, 1);

Here is the complete javascript code.

var canvasElement = document.getElementById("canvas");
var doc = new GLGE.Document();

doc.load("tutorial2.xml");

doc.onLoad = function() {
    var renderer = new GLGE.Renderer(canvasElement);
    var scene = new GLGE.Scene();
    scene = doc.getElement("mainScene");
    renderer.setScene(scene);

    setInterval(function(){
        renderer.render();
    }, 1);
}

Here it is—update, glge isn’t supported any more

A basic scene

Most GLGE scenes need three things: an HTML file, some javascript, and an XML file. You’ll also need to download GLGE.

I’m going to walk through setting up a simple scene with a flat triangle and a lighting source.

Lets start with the HTML file.

The HTML file

The HTML file does what you’d expect by setting up the basic structure of the web page. If you’re reading this tutorial you should have a solid grasp of HTML. Inside the body there is a canvas element with a width, height, and id, a script referencing GLGE and a place for our javascript.

<html>
    <head>
        <title>GLGE Demo</title>
    </head>
    <body>
        <canvas id="canvas" width="400" height="300"></canvas>

        <script type="text/javascript" src="/assets/js/lib/glge-compiled-min.js"></script>
        <script type="text/javascript">
            <!-- javascript goes here -->
        </script>
    </body>
</html>

And that’s it.

The XML file

The XML file defines the scene, lighting, cameras, and any objects. The very outside structure is this…

<?xml version="1.0"?>
    <glge>

    </glge>

Above is a bare GLGE document, which needs, at minimum, the following…

• At least one <mesh> composed of…
  • <positions>,
  • <normals>,
  • <uv1> and
  • <faces>,
• At least one <material>,
• A <camera> and
• A <scene> composed of…
  • At least one <object>
  • Optional <light>s.

Mesh

A <mesh> is what defines an object’s shape. Meshes can be generated by 3rd party software, or can be created by hand, as shown in this example. The simplest object defined by a mesh is a flat triangle, the building block for any object. The <mesh> behind a flat triangle is very simple.

It has four components, <positions>, <normals>, <uv1>, and <faces>. <positions> define corners in 3D space. In the syntax I prefer to use, each line defines x, y and z coordinates of one corner. The <normals> define the perpendicular direction from the surface, which plays into how lighting is computed. In the syntax I use, each line defines x, y and z coordinates of one normal of a corner. The <uv1> defines how an (image) texture is applied to the object. The triangle we’re creating is a solid color, so a <uv1> is not strictly necessary. In my syntax, each line is an x and y coordinate on the flat triangle. The last part, the <faces>, define how each point is used. The renderer draws the 0th point first (position -1, 1, 0; normal 0, 0, 1; and uv1 0, 0) then moves to the 1st and so on.

<mesh id="triangle">
    <positions>
        -1,  1, 0,
        -1, -1, 0,
         1, -1, 0
    </positions>
    <normals>
        0, 0, 1,
        0, 0, 1,
        0, 0, 1
    </normals>
    <uv1>
        0, 0,
        1, 0,
        1, 1
    </uv1>
    <faces>
        0, 1, 2
    </faces>
</mesh>

Material

If the XML document only contained a mesh, we still wouldn’t see anything. It’s just the definition of an object, not the object itself. The next thing needed is a <material>. A <material> defines an image or color to apply to the object and how lighting affects it.

The simple <material> defined in my example has three parts. An id to identify the element, a specular shine value (think reflection), and a color. The specular value is a value from 0 to 1. The color can be a hexadecimal or rgb value.

<material id="triangleMat" specular="1" color="#aaa" />

Camera

Now we have the shape of an object and what it will look like defined. Next we need to create a <camera> to see it from.

The <camera> is composed of an id and the values for it’s location and angle. The location is defined by the attributes loc_x, loc_y, and loc_z. The rotation is defined by the attributes rot_x, rot_y, and rot_z in units of radians. In my example, I don’t need location or rotation attributes because they are at the origin, 0, the default. A default camera is at point 0, 0, 0 and is looking straight down.

<camera id="mainCamera" loc_x="0" loc_y="0" loc_z="0" rot_x="0" rot_y="0" rot_z="0" />

/* same as */

<camera id="mainCamera" />

Scene

Now we have an object and our frame of viewing reference. Next we can start setting up a scene, comprised of an id, a reference to the <camera> we set up and ambient lighting, defined by a color.

<scene id="mainScene" camera="#mainCamera" ambient_color="#fff">

</scene>

Inside our scene we can add <object>s and <light>s. My simple example has one <object> and one <light>, but the <light>’s is not necessary to see the object.

Object

The <object> has an id, a reference to the <mesh> set up earlier, location attributes (the same syntax as for the camera), rotation attributes, and scale attributes (scale_x, scale_y and scale_z). Again, the location and rotation attributes default to 0. The scale attributes default to 1. In my example, I’ve moved my triangle down (z axis) by 4 units so it’s not at the same location as the <camera>.

<object id="triangle" mesh="#triangle" material="#triangleMat" loc_x="0" loc_y="0" loc_z="-4" rot_x="0" rot_y="0" rot_z="0" scale_x="1" scale_y="1" scale_z="1" />

/* same as */

<object id="triangle" mesh="#triangle" material="#triangleMat" loc_z="-4" />

Light

Now we have a functioning scene that will work if we were to render it! But… I want to make it look a bit more three dimentional (we are using WebGL). So I’ll add a <light>. The light has an id, location, rotation, a color, and a type. Location and rotation are the same as <object>s and <camera>s. The type that I’m using is L_POINT for point lighting. A point light has a location and faces a certain direction.

<light id="mainlight" loc_x="10" loc_y="15" loc_z="10" rot_x="-1.3" color="#fff" type="L_POINT" />

Done!

So, that’s it for this basic GLGE XML document. Here’s it is in full.

<?xml version="1.0"?>
<glge>

    <mesh id="triangle">
        <positions>
            -1,  1, 0,
            -1, -1, 0,
             1, -1, 0
        </positions>
        <normals>
            0, 0, 1,
            0, 0, 1,
            0, 0, 1
        </normals>
        <uv1>
            0, 0,
            1, 0,
            1, 1
        </uv1>
        <faces>
            0, 1, 2
        </faces>
    </mesh>

    <material id="triangleMat" specular="1" color="#aaa" />

    <camera id="mainCamera" />

    <scene id="mainScene" camera="#mainCamera" ambient_color="#fff">
        <object id="triangle" mesh="#triangle" material="#triangleMat" loc_z="-4" />
        <light id="mainlight" loc_x="10" loc_y="15" loc_z="10" rot_x="-1.3" color="#fff" type="L_POINT" />
    </scene>

</glge>

The javascript

The javascript is pretty important. It sets up a GLGE environment, fetches all the data in the XML file, and renders it as a 3D scene. For this example, it’s pretty simple because there’s no action, movement or controls.

First, we need to get our canvas element.

var canvasElement = document.getElementById("canvas");

Then we create the GLGE environment.

var doc = new GLGE.Document();

Next we will load the XML file into the GLGE document.

doc.load("path/to/demo_xml.xml");

Now we set up a function to run once the XML file is loaded.

doc.onLoad = function() {

}

Inside this function we will create a renderer and scene.

var renderer = new GLGE.Renderer(canvasElement);
var scene = new GLGE.Scene();

Then we bind the scene in the javascript with the scene from the XML file.

scene = doc.getElement("mainScene");

Then we bind the renderer to the scene.

renderer.setScene(scene);

And finally, we render everything.

renderer.render();

Done!

Here’s all the javascript.

var canvasElement = document.getElementById("canvas");
var doc = new GLGE.Document();

doc.load("triangle.xml");

doc.onLoad = function() {
    var renderer = new GLGE.Renderer(canvasElement);
    var scene = new GLGE.Scene();
    scene = doc.getElement("mainScene");
    renderer.setScene(scene);
    renderer.render();
}

Here it is – update, glge isn’t supported any more

This is the scene described above.