3D-Studio Material-Library File Format (.mli)
Autodesk Ltd.
Document Revision 0.25
May 1996 by Robin Fercoq ( email robin@mail.fc-net.fr )
( Addition by Martin van Velsen on 8 December 1996, incorporated
some material by James Fleming (email: jaemz@lglass.com ) )
Thanks for previous work: the 3d-studio file format (.3ds) doc
rewritten by Martin van Velsen (email: vvelsen@ronix.ptf.hro.nl )
based on a work from Jim Pitts (email: jim@micronetics.com )
A lot of the chunks are still undocumented if you know what they do
please email me Robin Feroq, Martin van Velsen or Jim Pitts.
As I get more information on the file format,I will document it for
everyone to see. I will post this regurlarly to alt.3d and alt.3d-
studio and I can be contacted there if my email does not work.
Disclaimer.
This document describes the file format of the .mli files generated by
3d-studio by Autodesk. By using the information contained within you
free not to hold me liable if, from its use, you f^Hmuck something up.
OK?
A warning beforehand. This docs describes the format of mli files as used
by version the .3ds files of 3d-studio 3.0 and higher 3d-studio. You can
find this information at byte 29 in the binary file.
This document describes the matlibs .mli files generated by 3D-Studio 4
and I think it covers nearly all of its aspects. If not you can
contact me or Martin van Velsen or Jim Pitts to add or correct.
First parts of .3DS files include material definitions with the same
format than .mli, if you want to understand this part of .3DS files
you can refer to this document.
Structure
---------
3D-Studio binary files are made up of "chunks".
A chunk is a block : with an ID which identifies what it stands for,
a pointer to the next chunk (relative to the beginning of the chunk),
and a block of data or a set of subchunks (which allows a hierarchy),
or possibly none of these (void chunk).
Pointers point to the next chunk of the same level.
The pointer of the last chunk of a subset points to the next chunk
level above.
Chunk ID is 2 bytes, pointer is 4 bytes.
If I am not clear you can read the .3ds file format doc.
( posted on alt.3d and alt.3d-studio )
It can also be found at: "http://www.mediatel.lu"
Remember DOS standard for short and long integers: always
least significant byte first. I'll write in the natural
order (most significant first) except for file extracts.
Main chunk (level 0) 3DAA
--------------------------
The Main chunk is the whole .MLI file. Its ID is 3DAA and the pointer
is in fact the length of the file.
Beginning looks like: AA 3D A0 0F 00 00 ... (for a file of 4k)
Material chunk (level 1) AFFF
-----------------------------
There is only one type of chunk for level 1: the material chunk which
is the definition for one material.
This chunk can be found in .3DS files as a subchunk of the EDIT3DS chunk.
>From now its all the same with .3DS and .MLI .
Typical material chunk content (level 2 subchunks)
--------------------------------------------------
Id type function
A000 asciiz material name [the name terminated by a null char]
A010 S ambient color [RGB1 and RGB2]
A020 S diffuse color idem
A030 S specular color idem
A040 S shininess [amount of]
A041 S shin. strength "
A050 S transparency "
A052 S trans. falloff "
A053 S reflect blur "
A100 intsh material type [1=flat 2=gour. 3=phong 4=metal]
A084 S self illum [amount of]
A087 * V unknown
A240 * V some trans. falloff amount (not 0)
A250 * V some reflect. blur
A081 * V two sided
A083 * V transparency ADD
A085 * V wire on
A088 * V face map
A08A * V trans. falloff IN
A08C * V soften
A08e * V 3d wire thickness in units (default is in pix)
A087 float wire thickness (always present, in case of forced
wire rendering)
S -> subchunks
V -> void
intsh -> short int (2 bytes)
intlo -> long int (4 bytes)
* -> optional. Absence of such a chunk leads to "none" or
to a default value.
Order respected (as 3DS saves the .MLI)
Non optional chunks are always present.
Subchunks of these material characteristics (level 3)
-----------------------------------------------------
0011 RGB1
0012 RGB2
Each of the three color chunks have 2 subchunks that defines their
colors. It seems that RGB1 is the color with a gamma (which one ?)
and RGB2 is the same color but as displayed on top of the material
editor window. But I'm not quite sure why there is two aspects
of the same color and what it does.
Anyway, in material color chunks there is always these two subchunks.
0030 "amount of"
A252 "displayed amount of bump"
The 0030 value seems to occur all through the file and will be
define as:
#define DOUBLE_BYTE 0x0030
A short integer that corresponds to the value displayed.
The transparency through relfection blur contain only DOUBLE_BYTE
chunks. Transparency and blur are just defined by the first byet of
the double byte. And the fall-off uses both bytes, the first for the
fall off, and the second for the siede fall off.
Oh, the nice maps
-----------------
Map and mask chunks (level 2) come after the material characteristics.
(just after the A087 chunk)
All these chunks are optional and have subchunks.
Map chunks IDs:
map mask
texture1 A200 A33E
texture2 A33A A340
opacity A210 A342
bump A230 A344
specular A204 A348
shininess A33C A346
self illum A33D A34A
reflection A220 A34C
In order to respect the order (well, I know, all this is terribly boring)
(but I wont joke) (actually, I have no sense of humour)
(if I had I wouldn't spend my time with computer binary files, would I ?)
(and especialy not this one...)
the chunk of the mask of a map follows the chunk of this map.
It may be of no importance at all thanks to the chunk structure...
Typical map or mask chunk content (more level 3 subchunks)
----------------------------------------------------------
0030 intsh amount of
A300 asciiz map's file name
A351 intsh map options
A353 float map filtering blur ( 7% -> 0.07 )
A354 * float 1/U scale
A356 * float 1/V scale
A358 * float U offset
A35A * float V offset
A35C * float map rotation angle
/A360 * RGB lum or alpha tint first color (default=00 00 00)
\A362 * RGB lum or alpha tint secnd color (default=FF FF FF)
/A364 * RGB RGB tint R channel color (default=FF 00 00)
A366 * RGB RGB tint G channel color (default=00 FF 00)
\A368 * RGB RGB tint B channel color (default=00 00 FF)
Some optional chunks may or may not be present in a given
map or mask chunk, depending on the options there is
for the specific map, or for masks.
--The map options chunk contains two bytes with options coded by bits.
If read as a short int (ls byte first):
bit4 bit0: 00 tile (default) 11 decal 01 both
bit 1: mirror
bit 2: not used ? (0)
bit 3: negative
bit 5: summed area map filtering (instead of pyramidal)
bit 6: use alpha (toggles RGBluma/alpha. For masks RGB means RGBluma)
bit 7: there is a one channel tint (either RGBluma or alpha)
bit 8: ignore alpha (take RGBluma even if an alpha exists (?))
bit 9: there is a three channel tint (RGB tint)
... not used (0)
Specific maps
-------------
-bump
For some reason 3DS divides the amount of bump by 4.
( in the DOUBLE_BYTE ( 0030 ) chunk )
Nevertheless, the amount actually seen in the material editor
is coded in a specific subchunk of the bump map chunk: A252
Just after the A300 chunk.
-reflection
The reflection map has no A351 or A353 chunks since there are no
options for reflection mapping.
If the map name is only a null caracter, then we have :
-automatic reflection A310
A level 2 chunk just after the reflection chunk when there is
autoreflection. This chunk contains two short ints and two long ints.
1st short contains 0004. (what does that mean ?)
2nd short codes for options:
bit0 1 (seems always set to 1)
bit1 0
bit2 0
bit3 First frame only
bit4 flat mirror
bitx 0
next comes a long for the map size
and the last long is for the "every Nth frame"
And there it is