cl wavefront

1.0.0

A library to parse the Wavefront OBJ file format.

About cl-wavefront

This library implements the Wavefront OBJ 3D model format.

How To

Load the library, and parse a file:

(org.shirakumo.fraf.wavefront:parse #p"my-file.obj")

It'll return a context which holds the vertices, uvs, normals, materials, groups, and objects defined by the file. You can parse either obj or mtl files. If the obj references an mtl file, it is automatically parsed as well.

The format defines mesh data rather loosely, allowing different materials per face, different face referencing mechanisms, varying indices per vertex attributes, and so on, which makes it rather hard to directly use for rendering. To convert an entire file, specific object, or specific face group, you can call extract-meshes.

This will instead return a list of mesh instances, which have the vertex-data normalised and packed into a single vector, and deduplicated indices into an index-data vector. Each mesh also has only a single material, vertex attributes set, and face-length, which should simplify rendering a lot.

Note that meshes still do not guarantee triangular meshes. If the source data contains quads or other polygons, you must tessellate the mesh yourself.

To Do

This library currently only supports polygonal meshes. Other features such as points, curves, surfaces, and more are not included, but should be easy to add into the existing parser framework if needed.

System Information

Version: 1.0.0

Dependencies:

Author: Nicolas Hafner

License: zlib

Homepage: https://shirakumo.github.io/cl-wavefront/

Bug Tracker: https://github.com/shirakumo/cl-wavefront/issues

Sources: https://github.com/shirakumo/cl-wavefront.git

Definition Index

ORG.SHIRAKUMO.FRAF.WAVEFRONT

No documentation provided.

EXTERNAL CLASS

CONTEXT

Source

Representation of all the data in a collection of OBJ and MTL files.

See EXTRACT-MESHES
See VERTICES
See UVS
See NORMALS
See GROUPS
See MATERIALS
See OBJECTS
See PARSE

EXTERNAL CLASS

FACE

Source

Representation of a face on a polygonal mesh.

All three arrays of VERTICES, UVS, NORMALS must be of the same length
and each contain indices into their respective arrays in the CONTEXT
of the FACE, modulo the size of each entry in the respective array.

Meaning for vertices, you should multiply the index by 4 to get the
index of the first coordinate of the vertex in the context's vertices
array, and for UVs and normals you should multiply the index by 3.

See VERTICES
See UVS
See NORMALS
See MATERIAL

EXTERNAL CLASS

GROUP

Source

Representation of a group of faces.

See EXTRACT-MESHES
See NAMED-OBJECT
See FACES
See LOD

EXTERNAL CLASS

MATERIAL

Source

Representation of a material defined in a Wavefront MTL file.

See NAMED-OBJECT
See ILLUMINATION-MODEL
See AMBIENT-FACTOR
See DIFFUSE-FACTOR
See SPECULAR-FACTOR
See SPECULAR-EXPONENT
See TRANSMISSION-FACTOR
See TRANSMISSION-FILTER
See REFRACTIVE-INDEX
See ROUGHNESS-FACTOR
See METALLIC-FACTOR
See SHEEN-FACTOR
See EMISSIVE-FACTOR
See AMBIENT-MAP
See DIFFUSE-MAP
See SPECULAR-MAP
See TRANSMISSION-MAP
See ROUGHNESS-MAP
See METALLIC-MAP
See SHEEN-MAP
See EMISSIVE-MAP
See BUMP-MAP
See DISPLACEMENT-MAP
See STENCIL-MAP
See NORMAL-MAP
See ROUGH-METAL-OCCLUSION-MAP

EXTERNAL CLASS

MESH

Source

Representation of packed vertex data.

See VERTEX-DATA
See INDEX-DATA
See ATTRIBUTES
See FACES-TO-MESH
See EXTRACT-MESHES

EXTERNAL CLASS

NAMED-OBJECT

Source

Superclass for all objects which may carry a name.

See NAME

EXTERNAL CLASS

OBJECT

Source

Representation of an "object".

An object encompasses one or more groups.

See EXTRACT-MESHES
See NAMED-OBJECT
See GROUPS

EXTERNAL CLASS

TEXTURE-MAP

Source

Representation of a texture map.

See FILE
See BLEND-U
See BLEND-V
See BOOST
See ORIGIN
See SCALE
See TURBULENCE
See RESOLUTION
See CLAMP
See MULTIPLIER
See BUMP-CHANNEL
See SPECULAR-TYPE

EXTERNAL FUNCTION

EXTRACT-MESHES

CONTEXT
&OPTIONAL
THING

Source

Extract a set of distinct meshes.

If no THING is given, all meshes present in the context are
extracted. Otherwise, you may pass a vector of FACEs, a GROUP, or an
OBJECT to extract meshes from.

As much as possible, names will be assigned to the resulting meshes.

See CONTEXT
See FACE
See GROUP
See OBJECT
See SHARED-FACES
See FACES-TO-MESH

EXTERNAL FUNCTION

FACES-TO-MESH

CONTEXT
FACES

Source

Constructs a MESH instance from the given FACES array.

The consequences are undefined if the faces in the mesh vary in the
number of faces they address, the number of properties they store, or
the material they reference.

See SHARED-FACES
See EXTRACT-MESHES

EXTERNAL FUNCTION

PARSE

SOURCE
&OPTIONAL
CONTEXT

Source

Parse an OBJ or MTL file from a file, stream, or string representation.

Returns a CONTEXT that contains the parsed data.
May parse recursively if other files are referenced by the file
contents.

If you pass in a CONTEXT, the contents will be added to the passed
context instance.

A warning is signalled for any unrecognised directives.
An error is signalled for any malformed directives.

See CONTEXT

EXTERNAL FUNCTION

SHARED-FACES

FACES

Source

Splits the given faces array into sets of face arrays that share the same properties.

Specifically they all must share the same material, face length, and
attributes.

EXTERNAL GENERIC-FUNCTION

AMBIENT-FACTOR

OBJECT

Accesses the ambient color factor.

This is a vector of three elements [ R G B ]

See METAL

EXTERNAL GENERIC-FUNCTION
(SETF AMBIENT-FACTOR)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

AMBIENT-MAP

OBJECT

Accesses the ambient texture map.

See MATERIAL
See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF AMBIENT-MAP)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

ATTRIBUTES

OBJECT

Accesses the list of attributes stored in the mesh's vertex data.

The order is significant. May contain the following:

 :POSITION  --- Three single-floats for the world-space position of
                the vertex.
 :NORMAL    --- Three single-floats for the normal vector of the
                vertex.
 :UV        --- Two single-floats for the U and V coordinates in the
                textures.

See MESH

EXTERNAL GENERIC-FUNCTION
(SETF ATTRIBUTES)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

BLEND-U

OBJECT

Accesses whether the texture should blend U coordinates.

See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF BLEND-U)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

BLEND-V

OBJECT

Accesses whether the texture should blend V coordinates.

See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF BLEND-V)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

BOOST

OBJECT

Accesses the boosting factor for mipmap sharpness.

See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF BOOST)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

BUMP-CHANNEL

OBJECT

Accesses the channel to use in the bump map texture.

See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF BUMP-CHANNEL)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

BUMP-MAP

OBJECT

Accesses the bump texture map.

See MATERIAL
See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF BUMP-MAP)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

CLAMP

OBJECT

Accesses whether the texture should repeat or be clamped to its edges.

See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF CLAMP)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

DIFFUSE-FACTOR

OBJECT

Accesses the diffuse color factor.

This is a vector of three elements [ R G B ]

See METAL

EXTERNAL GENERIC-FUNCTION
(SETF DIFFUSE-FACTOR)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

DIFFUSE-MAP

OBJECT

Accesses the diffuse texture map.

See MATERIAL
See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF DIFFUSE-MAP)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

DISPLACEMENT-MAP

OBJECT

Accesses the displacement texture map.

See MATERIAL
See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF DISPLACEMENT-MAP)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

EMISSIVE-FACTOR

OBJECT

Accesses the emissive factor.

This is a vector of three elements [ R G B ]

See METAL

EXTERNAL GENERIC-FUNCTION
(SETF EMISSIVE-FACTOR)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

EMISSIVE-MAP

OBJECT

Accesses the emissive texture map.

See MATERIAL
See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF EMISSIVE-MAP)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

FACE-LENGTH

OBJECT

Accesses the number of vertices per face in the mesh.

See MESH

EXTERNAL GENERIC-FUNCTION
(SETF FACE-LENGTH)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

FACES

OBJECT

Accesses the vector of faces belonging to the group.

See GROUP
See FACE

EXTERNAL GENERIC-FUNCTION
(SETF FACES)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

FILE

OBJECT

Accesses the relative pathname of the texture map.

See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF FILE)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

GROUPS

OBJECT

Accesses the hash table of groups.

Each group can be accessed via its name.

See OBJECT
See CONTEXT
See GROUP

EXTERNAL GENERIC-FUNCTION
(SETF GROUPS)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

ILLUMINATION-MODEL

OBJECT

Accesses the intended illumination model of the material.

0. Color on and Ambient off
1. Color on and Ambient on
2. Highlight on
3. Reflection on and Ray trace on
4. Transparency: Glass on, Reflection: Ray trace on
5. Reflection: Fresnel on and Ray trace on
6. Transparency: Refraction on, Reflection: Fresnel off and Ray trace on
7. Transparency: Refraction on, Reflection: Fresnel on and Ray trace on
8. Reflection on and Ray trace off
9. Transparency: Glass on, Reflection: Ray trace off
10. Casts shadows onto invisible surfaces

See METAL

EXTERNAL GENERIC-FUNCTION
(SETF ILLUMINATION-MODEL)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

INDEX-DATA

OBJECT

Accesses the vector of packed face indices.

This is a vector of (UNSIGNED-BYTE 32)s describing the vertex indices
that form the faces.

See MESH

EXTERNAL GENERIC-FUNCTION
(SETF INDEX-DATA)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

LOD

OBJECT

Accesses the level of detail the group should be visible at.

See GROUP

EXTERNAL GENERIC-FUNCTION
(SETF LOD)
- NEW-VALUE
- OBJECT
No documentation provided.
EXTERNAL GENERIC-FUNCTION
MATERIAL
- OBJECT
No documentation provided.
EXTERNAL GENERIC-FUNCTION
(SETF MATERIAL)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

MATERIALS

OBJECT

Accesses the materials table in the context.

Each material is indexed by its name.

See CONTEXT
See MATERIAL

EXTERNAL GENERIC-FUNCTION
(SETF MATERIALS)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

METALLIC-FACTOR

OBJECT

Accesses the metallic/metalness factor.

See METAL

EXTERNAL GENERIC-FUNCTION
(SETF METALLIC-FACTOR)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

METALLIC-MAP

OBJECT

Accesses the metallic texture map.

See MATERIAL
See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF METALLIC-MAP)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

MULTIPLIER

OBJECT

Accesses the multiplier factor for the bump map.

See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF MULTIPLIER)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

NAME

OBJECT

Accesses the string name of the object

See NAMED-OBJECT

EXTERNAL GENERIC-FUNCTION
(SETF NAME)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

NORMAL-MAP

OBJECT

Accesses the normal texture map.

See MATERIAL
See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF NORMAL-MAP)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

NORMALS

OBJECT

Accesses the normals of the object

For a FACE this is a vector of indices.
Fro a CONTEXT this is a vector of single floats.

See FACE
See CONTEXT

EXTERNAL GENERIC-FUNCTION
(SETF NORMALS)
- NEW-VALUE
- OBJECT
No documentation provided.
EXTERNAL GENERIC-FUNCTION
OBJECT
- OBJECT
No documentation provided.
EXTERNAL GENERIC-FUNCTION
(SETF OBJECT)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

OBJECTS

OBJECT

Accesses the objects table in the context.

Each object is indexed by its name.
There is always at least one object.

See CONTEXT
See OBJECT

EXTERNAL GENERIC-FUNCTION
(SETF OBJECTS)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

ORIGIN

OBJECT

Accesses the texture origin offset.

This is a vector of three elements [U V W]

See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF ORIGIN)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

REFRACTIVE-INDEX

OBJECT

Accesses the refractive index if transmissive.

See METAL

EXTERNAL GENERIC-FUNCTION
(SETF REFRACTIVE-INDEX)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

RESOLUTION

OBJECT

Accesses the texture's resolution.

This is a single value for square textures.

See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF RESOLUTION)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

ROUGH-METAL-OCCLUSION-MAP

OBJECT

Accesses the combined roughness/metal/occlusion texture map.

See MATERIAL
See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF ROUGH-METAL-OCCLUSION-MAP)
- NEW-VALUE
- OBJECT
No documentation provided.
EXTERNAL GENERIC-FUNCTION
ROUGHNESS-FACTOR
- OBJECT
```
Accesses the roughness factor.

See METAL
```
EXTERNAL GENERIC-FUNCTION
(SETF ROUGHNESS-FACTOR)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

ROUGHNESS-MAP

OBJECT

Accesses the roughness texture map.

See MATERIAL
See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF ROUGHNESS-MAP)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

SCALE

OBJECT

Accesses the texture scale factor.

This is a vector of three elements [U V W]

See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF SCALE)
- NEW-VALUE
- OBJECT
No documentation provided.
EXTERNAL GENERIC-FUNCTION
SHEEN-FACTOR
- OBJECT
```
Accesses the sheen factor.

See METAL
```
EXTERNAL GENERIC-FUNCTION
(SETF SHEEN-FACTOR)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

SHEEN-MAP

OBJECT

Accesses the sheen texture map.

See MATERIAL
See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF SHEEN-MAP)
- NEW-VALUE
- OBJECT
No documentation provided.
EXTERNAL GENERIC-FUNCTION
SPECULAR-EXPONENT
- OBJECT
```
Accesses the specular exponent.

See METAL
```
EXTERNAL GENERIC-FUNCTION
(SETF SPECULAR-EXPONENT)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

SPECULAR-FACTOR

OBJECT

Accesses the specular color factor.

This is a vector of three elements [ R G B ]

See METAL

EXTERNAL GENERIC-FUNCTION
(SETF SPECULAR-FACTOR)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

SPECULAR-MAP

OBJECT

Accesses the specular texture map.

See MATERIAL
See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF SPECULAR-MAP)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

STENCIL-MAP

OBJECT

Accesses the stencil decal texture map.

See MATERIAL
See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF STENCIL-MAP)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

TEXTURE-TYPE

OBJECT

Accesses the type of the texture.

This can be sphere, cube_top, cube_bottom...

See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF TEXTURE-TYPE)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

TRANSMISSION-FACTOR

OBJECT

Accesses the transmission factor.

0.0 means opaque
1.0 means transparent

See METAL

EXTERNAL GENERIC-FUNCTION
(SETF TRANSMISSION-FACTOR)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

TRANSMISSION-FILTER

OBJECT

Accesses the transmission color filter.

This is a vector of three elements [ R G B ]

See METAL

EXTERNAL GENERIC-FUNCTION
(SETF TRANSMISSION-FILTER)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

TRANSMISSION-MAP

OBJECT

Accesses the transmission texture map.

See MATERIAL
See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF TRANSMISSION-MAP)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

TURBULENCE

OBJECT

Accesses the texture turbulence factor.

This is a vector of three elements [U V W]

See TEXTURE-MAP

EXTERNAL GENERIC-FUNCTION
(SETF TURBULENCE)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

UVS

OBJECT

Accesses the UV coordinates of the object

For a FACE this is a vector of indices.
Fro a CONTEXT this is a vector of single floats.

See FACE
See CONTEXT

EXTERNAL GENERIC-FUNCTION
(SETF UVS)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

VERTEX-DATA

OBJECT

Accesses the vector of packed vertices.

This is a vector of SINGLE-FLOATs, with the per-vertex data tightly
packed for easy upload to the GPU. The attributes stored per vertex is
described in the ATTRIBUTES list. The number of vertices per face is
stored in the FACE-LENGTH of the mesh. The material to use for every
face in the mesh is in MATERIAL.

See MESH
See ATTRIBUTES
See FACE-LENGTH

EXTERNAL GENERIC-FUNCTION
(SETF VERTEX-DATA)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

VERTICES

OBJECT

Accesses the vertices of the object

For a FACE this is a vector of indices.
Fro a CONTEXT this is a vector of single floats.

See FACE
See CONTEXT

EXTERNAL GENERIC-FUNCTION
(SETF VERTICES)
- NEW-VALUE
- OBJECT
No documentation provided.