Zen and the Art of OBJ 1: The Anatomy of an OBJ

A number of people are working on an update to Jonathan's Blender X-Plane export scripts; this post is aimed at shedding some light on some of the recent changes to the OBJ format. X-Plane 9 introduced a number of new OBJ features (manipulators, invisible geometry and camera collisions, dataref-driven control of emissive texturing, normal maps, and a number of new light billboard options). If you simply read the new OBJ commands in the order they were added to the format, it's just a soup of funny names. But there is some logic to how the OBJ format is extended.

The World's Simplest OBJ

Here is a very simple OBJ file, broken up by my annotations. First we have the header and global section:

A
800
OBJ

TEXTURE great_image.dds
POINT_COUNTS 24 0 0 36

the global section describes properties universal to the entire OBJ. For example, what textures will be used to draw the object?

We picked up a few new global properties in the version 9 run:

• Normal maps are declared globally for the entire OBJ.
• The metrics of any panel regions to be used are declared globally.

We may pick up new global attributes in the future; if we do, they will be properties that apply to the entire obj.

Next comes the data section:

VT 0.449997 0.300003 0.860001 1.000000 0.000000 0.000000 0.000000 0.000000
VT 0.449997 0.300003 0.000000 1.000000 0.000000 0.000000 0.000000 1.000000
VT 0.449997 -0.509995 0.860001 1.000000 0.000000 0.000000 1.000000 0.000000
...
IDX10 0 1 2 3 2 1 4 5 6 7
...
IDX 21

I have removed a lot of the data section, because there's not much to be said about it. The data section contains the raw data for the meshes in your OBJ, and it hasn't changed since the OBJ 8 format was introduced.

The third and final section is the most interesting one: the commands section.

ATTR_LOD 0 3000
ATTR_hard asphalt
TRIS 0 36

The commands section describes how the data is used in the form of serial instructions to X-Plane. Most changes to the OBJ format have come in the form of new commands. We can categorize our commands into a few buckets:

• Drawing commands create "stuff". There aren't very many drawing commands, and new ones don't appear very frequently. TRIS and LINES are the main commands, but the smoke commands also fall into this category, as do the light billboard commands. The new light billboard command LIGHT_PARAM is the only new drawing command for version 9, and it probably warrants its own blog post.
• Attribute commands change how stuff is drawn - they effectively define properties for drawing on all triangles that can be modified. We picked up a number of new attributes: manipulators (controlling how the mouse works), light level control, solid camera, draw disabling, deck style hard surfaces, and panel regions. (While you must declare the panel region locations globally, a panel region is enabled for a specific batch.)
• ATTR_LOD is sort of an exception, because it defines the structure of the model (e.g. a model with LOD really contains several separate command lists, of which only one is used).
  

Most new extensions to the OBJ format come in the form of new attributes. Attributes generally apply to a specific mesh within your model, not to the entire model.

Note that attributes can be thought of as "per mesh" or "per batch" properties, because they affect only the batches of mesh (TRIS commands) between the attribute being turned on and turned back off again.

Where Will New Features Appear?

I try to post some of my crazier ideas regarding OBJ on the scenery system RFCs page. Looking at the extensions, we can see how these extensions will all be either global, drawing primitive, attribute, or OBJ structure extensions. (I am not promising that any of these RFCs will be implemented, just showing how the OBJ format grows.)

• Additive LOD. This is a change to the structure of an OBJ, but it doesn't actually change the format, just the legal LOD values.
• Explicit OBJ Height. This is a global property on the OBJ.
• Global Texture Variants would be a global property on the OBJ's textures.
• Global Object Attributes are new global properties - they move some per-batch attributes to be object-wide.
• Draped Object Geometry would be per batch.

In summary, the vast majority of proposed extensions are new per batch or per object properties.

Next: what are the implications on performance of the various sections of an OBJ?