Web 3D Content Overview

While you can make a simple 3D Website using just the standard Pkg objects like Ground and Sky, you may want to use your own 3D models to make a more interesting Website. This document explains how to use 3D models in a 3D Website.

3D Models can be created using 3D modelling software, or bought or downloaded from the internet. Lateral Visions 3D Web browser supports 3D models in the obj and Collada (.dae) formats, although other formats will be supported in future as well.

Collada, characterized by the '.dae' extension, is a general purpose 3D model interchange format. Most 3D modelling software either exports to the Collada format or can be easily extended to export to Collada; it is becoming a standard format for 3D models.

It may be necessary to tweak material properties to get them looking their best in the 3D Web browser. It is possible to use lightmap textures by placing them in the ambient material channel in the collada file. The details of this are beyond the scope of this overview.

The 'Obj' format, characterized by files with a '.obj' extension, is a 3D format now supported by many 3D modelling software packages.

Because the Obj format does not store material information in the obj file itself (and the 3D Web browser does not support the use of companion mtllib files), the ability to specify material properties with obj files is limited. The 'usemap' keyword can however be used in the Obj file to specify a texture filename.

Currently only jpg format images are supported. The jpg format does not support an alpha channel; however, if a texture is called xxx_rgb.jpg, then the system will automatically try and load another texture called xxx_a.jpg onto the Textures alpha channel. This _a texture will usually just be a gray scale alpha channel image. In this way, a full texture with red, green, blue and alpha channels can be loaded.

Note that inline linking (directly using resources on another website without hosting them on your own) is not currently allowed for 3D model files, although it is allowed for images used for textures. Thus any resources used by a 3D website must be made accessible on the same origin (usually the same domain) as the 3D website. In future, Access Control will be used to control which content can be accessed by a given 3D website.

Because different modelling software and different modellers use different conventions for scales and axes, the 3D Web browser does not attempt to deal with these issues on import. As a consequence, it may be necessary to apply a transform to the 3D model to get it to appear the right way up, in the right place, and to the right scale. If you see nothing when loading a model, it may be because the model is huge, tiny or far away. The default unit scale for a 3D website is meters; clipping distances, movement speeds and so on are set to reasonable default values assuming walking around a human-scale environment specified in meters. This can be changed, either because a world is needed on a much larger or smaller scale, or because other units are desired.

To load a model into a 3D Website, use either an Actor or a Stator. Actors are 3D models that can move about dynamically (ie whose XformW can be changed dynamically). Stators are 3D models that cannot be moved after they are first created. Unless you need to be able to move the 3D model around dynamically, it is generally better to use a stator. The Pkg.ManagedActor and Pkg.ManagedStator classes provide Stators and Actors, although it is usually better to create them using a Factory:

App.Model = Pkg.ManagedFactory.New():CreateStator({
	meshUrl = "foo.dae",
	texturePath = "bar/",
	xform = XformW(1, Core.Math.Yaw(math.pi/2), WorldPos(20, -7.20, -20))
})
				

The above code creates a new Stator, rotates it and places at a specific location in the World. The 'meshUrl' parameter specifies the 3D model file to load (a Collada dae file in this case). The url is resolved relative to the main World Descriptor file. The texturePath is an url-base that specifies a directory where texture files can be found for this model; again this is resolved relative to the main World Descriptor file. Note that as with all lua objects, if references to the created Actor or Stator are lost, it will be garbage collected and removed from the world.

Normally, every call to create a Stator, Actor, Mesh, Material or Texture goes through a Factory object. The Pkg.ManagedFactory class provides the standard, default factory behavior. However, it is possible to define custom factories that can alter the loading behavior for 3D models. For example:

-- Factory
local factory = Pkg.ManagedFactory.New()
local CreateTextureOld = factory.CreateTexture
function factory:CreateTexture (info) -- Override the CreateTexture function
	if string.find(info.url, "map") then
		info.width = 256
		info.height = 256
	end
	return CreateTextureOld(self, info)
end

-- Model
App.Model = factory:CreateStator({meshUrl = "foo.obj", texturePath = "bar/", scale = 0.2})
				

The above code first creates a new factory based on the standard ManagedFactory. It then overrides the factory's CreateTexture function. The new CreateTexture function forces all textures with 'map' in their url to load at a resolution of 256x256, whetever their original dimensions were. A Stator is then created using the new factory. Any textures with 'map' in the url loaded for this Stator will be 256x256.

The same approach can be used with the CreateMaterial function to override material properties such as color, specular, reflection, texture and so on.

Factories can be useful, especially for overriding material and texture properties. For example, it is possible to force a particular material to use anisotropic filtering, or to make a light map texture use the L8 format instead of DXT.