ref: d1dbc002287de52e837af551e2a3a03678cc4bb4
dir: /obj.2.man/
.TH OBJ 2
.SH NAME
objaddvertex, objaddelem, objallocelem, objaddelemidx, objfreeelem,
objallocobject, objfreeobject, objpushobject, objgetobject,
objfreetexture, objallocmt, objfreemt, objallocmtl, objaddmtl,
objgetmtl, objparse, objfree, objmtlparse, objmtlfree, objexport,
OBJMaterlistfmt, OBJfmt, OBJfmtinstall
\- OBJ parser
.SH SYNOPSIS
.ta 0.7i +0.7i +0.7i +0.7i +0.7i +0.7i +0.7i
.EX
#include <u.h>
#include <libc.h>
#include <obj.h>
/* vertex types */
enum {
OBJVGeometric,
OBJVTexture,
OBJVNormal,
OBJVParametric,
OBJNVERT
};
/* element types */
enum {
OBJEPoint,
OBJELine,
OBJEFace,
};
/* object hash table size */
enum {
OBJHTSIZE = 17
};
typedef union OBJVertex OBJVertex;
typedef struct OBJColor OBJColor;
typedef struct OBJTexture OBJTexture;
typedef struct OBJVertexArray OBJVertexArray;
typedef struct OBJIndexArray OBJIndexArray;
typedef struct OBJMaterial OBJMaterial;
typedef struct OBJMaterlist OBJMaterlist;
typedef struct OBJElem OBJElem;
typedef struct OBJObject OBJObject;
typedef struct OBJ OBJ;
#pragma varargck type "O" OBJ*
#pragma varargck type "M" OBJMaterlist*
union OBJVertex
{
struct { double x, y, z, w; }; /* geometric */
struct { double u, v, vv; }; /* texture and parametric */
struct { double i, j, k; }; /* normal */
};
struct OBJColor
{
double r, g, b, a;
};
struct OBJTexture
{
char *filename;
Memimage *image;
};
struct OBJVertexArray
{
OBJVertex *verts;
int nvert;
};
struct OBJIndexArray
{
int *indices;
int nindex;
};
struct OBJMaterial
{
char *name;
OBJColor Ka; /* ambient color */
OBJColor Kd; /* diffuse color */
OBJColor Ks; /* specular color */
OBJColor Ke; /* emissive color */
double Ns; /* specular highlight */
double Ni; /* index of refraction */
double d; /* dissolution factor (opacity) */
int illum; /* illumination model */
OBJTexture *map_Kd; /* color texture file */
OBJTexture *map_Ks; /* specular texture file */
OBJTexture *norm; /* normal texture file */
OBJMaterial *next;
};
struct OBJMaterlist
{
char *filename;
OBJMaterial *mattab[OBJHTSIZE];
};
struct OBJElem
{
OBJIndexArray indextab[OBJNVERT];
int type;
OBJMaterial *mtl;
OBJElem *next;
};
struct OBJObject
{
char *name;
OBJElem *child;
OBJElem *lastone;
OBJObject *next;
};
struct OBJ
{
OBJVertexArray vertdata[OBJNVERT];
OBJObject *objtab[OBJHTSIZE];
OBJMaterlist *materials;
};
void objaddvertex(OBJ *obj, OBJVertex v, int vtype)
void objaddelem(OBJObject *o, OBJElem *e)
OBJElem *objallocelem(int t)
void objaddelemidx(OBJElem *e, int idxtab, int idx)
void objfreeelem(OBJElem *e)
OBJObject *objallocobject(char *n)
void objfreeobject(OBJObject *o)
void objpushobject(OBJ *obj, OBJObject *o)
OBJObject *objgetobject(OBJ *obj, char *n)
void objfreetexture(OBJTexture *t)
OBJMaterial *objallocmt(char *name)
void objfreemt(OBJMaterial *m)
OBJMaterlist *objallocmtl(char *file)
void objaddmtl(OBJMaterlist *ml, OBJMaterial *m)
OBJMaterial *objgetmtl(OBJMaterlist *ml, char *name)
OBJ *objparse(char *path)
void objfree(OBJ *obj)
OBJMaterlist *objmtlparse(char *path)
void objmtlfree(OBJMaterlist *ml)
int objexport(char *dstdir, OBJ *obj)
int OBJMaterlistfmt(Fmt *f)
int OBJfmt(Fmt *f)
void OBJfmtinstall(void)
.EE
.SH DESCRIPTION
This library provides a parser for the Wavefront OBJ 3d scene
description file format.
Objects are stored in a hash table within an
.B OBJ
structure, along with vertex data and materials. Each
.B OBJObject
contains a list of children
.BR OBJElem s
(elements), and each of these elements contains a table of indices
and a reference to a material, used to represent its mesh.
.PP
.B Objaddvertex
adds vertex
.I v
to the vertex table
.I vtype
in
.I obj.
.PP
.B Objaddelem
appends an element to
.IR o 's
list of children.
.PP
.B Objallocelem
allocates a new element of type
.IR t .
.PP
.B Objaddelemidx
pushes the index
.I idx
into the vertex type table
.IR idxtab .
.PP
.B Objfreeelem
frees the element along with its index tables.
.PP
.B Objallocobject
allocates a new object with name
.IR n ,
which cannot be
.BR nil .
.PP
.B Objfreeobject
frees the passed object and all of its children elements.
.PP
.B Objpushobject
adds the object
.I o
to
.IR obj 's
hash table.
.IR O 's
name should be unique, otherwise the existing homonymous object will
be replaced by it.
.PP
.B Objgetobject
retrieves the object named
.I n
from the
.IR obj .
It returns
.B nil
if none is found.
.PP
.B Objfreetexture
frees the texture and its associated
.BR Memimage .
.PP
.B Objallocmt
creates a material named
.IR name .
Just like with the objects, it must be unique and not
.BR nil .
.PP
.B Objfreemt
frees the material along with all of its textures.
.PP
.B Objallocmtl
creates an empty material list with file name
.IR file .
This
.I file
is used for serialization (see
.BR OBJMaterlistfmt .)
.PP
.B Objaddmtl
appends
.I m
to the list of materials in
.IR ml .
.PP
.B Objgetmtl
looks up in
.I ml
for a material with name
.I name
and returns it if found,
.B nil
otherwise.
.PP
.B Objparse
takes the
.I path
to an
.B .obj
file and returns a pointer to a dynamically allocated
.B OBJ
structure filled with its content. Object and material names, as well
as material list and texture file names are preserved.
.PP
.B Objfree
takes a pointer to a previously allocated
.B OBJ
structure and frees it along with all of its content, including
textures (see
.BR OBJTexture .)
.PP
.B Objmtlparse
reads the
.B .mtl
file provided at
.I path
and returns a pointer to an allocated
.B OBJMaterlist
structure, which contains the list of materials extracted from it.
.PP
.B Objmtlfree
takes a pointer to a previously allocated
.B OBJMaterlist
and releases its memory and that of its members.
.PP
.B Objexport
creates a file structure within the directory
.IR dstdir ,
writing the serialized
.I obj
into a file named
.BR main.obj ,
and its
.B OBJMaterlist
into another file named after its
.I filename
property. It also creates a file for every
texture referenced by the materials, formatting them based on the
.B OBJTexture
.I filename
property's extension (which can be any of
.B .png
or
.BR .jpe?g .)
.PP
.B OBJfmt
is a formatting routine used to serialize an
.B OBJ
structure into text, and
.B OBJMaterlistfmt
does the same for
.B OBJMaterlist
structures. You can install them for a custom format label, or use
the
.B OBJfmtinstall
procedure provided with this library to install them for the
.B %O
and
.B %M
labels respectively.
.SH SOURCE
.B /sys/src/libobj
.SH SEE ALSO
.IR geometry (2),
.IR fmtinstall(2)
.br
http://paulbourke.net/dataformats/obj
.br
https://people.sc.fsu.edu/~jburkardt/data/obj/obj.html
.br
https://paulbourke.net/dataformats/mtl/
.br
https://www.loc.gov/preservation/digital/formats/fdd/fdd000508.shtml
.br
https://people.computing.clemson.edu/~dhouse/courses/405/docs/brief-obj-file-format.html
.SH DIAGNOSTICS
All the routines write to
.IR errstr (2)
in the event of failure, and return either nil or -1.
.SH BUGS
There are probably some in the parser. It should be simpler.
.PP
Objexport uses an internal 8KB buffer for
.IR fmt (2)
writes that can overflow libthread stacks. If you're getting weird
errors with
.IR malloc (2)
and friends after using it in your program, increase the
mainstacksize.