diff --git a/docs/b3d_specification.txt b/docs/b3d_specification.txt deleted file mode 100644 index 81c8625..0000000 --- a/docs/b3d_specification.txt +++ /dev/null @@ -1,260 +0,0 @@ -************************************************************************************ -* Blitz3d file format V0.01 * -************************************************************************************ - -This document and the information contained within is placed in the Public Domain. - -Please visit http://www.blitzbasic.co.nz for the latest version of this document. - -Please contact marksibly@blitzbasic.co.nz for more information and general inquiries. - - - -************************************************************************************ -* Introduction * -************************************************************************************ - -The Blitz3D file format specifies a format for storing texture, brush and entity descriptions for -use with the Blitz3D programming language. - -The rationale behind the creation of this format is to allow for the generation of much richer and -more complex Blitz3D scenes than is possible using established file formats - many of which do not -support key features of Blitz3D, and all of which miss out on at least some features! - -A Blitz3D (.b3d) file is split up into a sequence of 'chunks', each of which can contain data -and/or other chunks. - -Each chunk is preceded by an eight byte header: - -char tag[4] ;4 byte chunk 'tag' -int length ;4 byte chunk length (not including *this* header!) - -If a chunk contains both data and other chunks, the data always appears first and is of a fixed -length. - -A file parser should ignore unrecognized chunks. - -Blitz3D files are stored little endian (intel) style. - -Many aspects of the file format are not quite a 'perfect fit' for the way Blitz3D works. This has -been done mainly to keep the file format simple, and to make life easier for the authors of third -party importers/exporters. - - - -************************************************************************************ -* Chunk Types * -************************************************************************************ - -This lists the types of chunks that can appear in a b3d file, and the data they contain. - -Color values are always in the range 0 to 1. - -string (char[]) values are 'C' style null terminated strings. - -Quaternions are used to specify general orientations. The first value is the quaternion 'w' value, -the next 3 are the quaternion 'vector'. A 'null' rotation should be specified as 1,0,0,0. - -Anything that is referenced 'by index' always appears EARLIER in the file than anything that -references it. - -brush_id references can be -1: no brush. - -In the following descriptions, {} is used to signify 'repeating until end of chunk'. Also, a chunk -name enclosed in '[]' signifies the chunk is optional. - -Here we go! - - -BB3D - int version ;file format version: default=1 - [TEXS] ;optional textures chunk - [BRUS] ;optional brushes chunk - [NODE] ;optional node chunk - -The BB3D chunk appears first in a b3d file, and its length contains the rest of the file. - -Version is in major*100+minor format. To check the version, just divide by 100 and compare it with -the major version your software supports, eg: - -if file_version/100>my_version/100 - RuntimeError "Can't handle this file version!" -EndIf - -if file_version Mod 100>my_version Mod 100 - ;file is a more recent version, but should still be backwardly compatbile with what we can -handle! -EndIf - - -TEXS - { - char file[] ;texture file name - int flags,blend ;blitz3D TextureFLags and TextureBlend: default=1,2 - float x_pos,y_pos ;x and y position of texture: default=0,0 - float x_scale,y_scale ;x and y scale of texture: default=1,1 - float rotation ;rotation of texture (in radians): default=0 - } - -The TEXS chunk contains a list of all textures used in the file. - -The flags field value can conditional an additional flag value of '65536'. This is used to indicate that the texture uses secondary UV values, ala the TextureCoords command. Yes, I forgot about this one. - - -BRUS - int n_texs - { - char name[] ;eg "WATER" - just use texture name by default - float red,green,blue,alpha ;Blitz3D Brushcolor and Brushalpha: default=1,1,1,1 - float shininess ;Blitz3D BrushShininess: default=0 - int blend,fx ;Blitz3D Brushblend and BrushFX: default=1,0 - int texture_id[n_texs] ;textures used in brush - } - -The BRUS chunk contains a list of all brushes used in the file. - - -VRTS: - int flags ;1=normal values present, 2=rgba values present - int tex_coord_sets ;texture coords per vertex (eg: 1 for simple U/V) max=8 - int tex_coord_set_size ;components per set (eg: 2 for simple U/V) max=4 - { - float x,y,z ;always present - float nx,ny,nz ;vertex normal: present if (flags&1) - float red,green,blue,alpha ;vertex color: present if (flags&2) - float tex_coords[tex_coord_sets][tex_coord_set_size] ;tex coords - } - -The VRTS chunk contains a list of vertices. The 'flags' value is used to indicate how much extra -data (normal/color) is stored with each vertex, and the tex_coord_sets and tex_coord_set_size -values describe texture coordinate information stored with each vertex. - - -TRIS: - int brush_id ;brush applied to these TRIs: default=-1 - { - int vertex_id[3] ;vertex indices - } - -The TRIS chunk contains a list of triangles that all share a common brush. - - -MESH: - int brush_id ;'master' brush: default=-1 - VRTS ;vertices - TRIS[,TRIS...] ;1 or more sets of triangles - -The MESH chunk describes a mesh. A mesh only has one VRTS chunk, but potentially many TRIS chunks. - - -BONE: - { - int vertex_id ;vertex affected by this bone - float weight ;how much the vertex is affected - } - -The BONE chunk describes a bone. Weights are applied to the mesh described in the enclosing ANIM - -in 99% of cases, this will simply be the MESH contained in the root NODE chunk. - - -KEYS: - int flags ;1=position, 2=scale, 4=rotation - { - int frame ;where key occurs - float position[3] ;present if (flags&1) - float scale[3] ;present if (flags&2) - float rotation[4] ;present if (flags&4) - } - -The KEYS chunk is a list of animation keys. The 'flags' value describes what kind of animation -info is stored in the chunk - position, scale, rotation, or any combination of. - - -ANIM: - int flags ;unused: default=0 - int frames ;how many frames in anim - float fps ;default=60 - -The ANIM chunk describes an animation. - - -NODE: - char name[] ;name of node - float position[3] ;local... - float scale[3] ;coord... - float rotation[4] ;system... - [MESH|BONE] ;what 'kind' of node this is - if unrecognized, just use a Blitz3D -pivot. - [KEYS[,KEYS...]] ;optional animation keys - [NODE[,NODE...]] ;optional child nodes - [ANIM] ;optional animation - -The NODE chunk describes a Blitz3D Entity. The scene hierarchy is expressed by the nesting of NODE -chunks. - -NODE kinds are currently mutually exclusive - ie: a node can be a MESH, or a BONE, but not both! -However, it can be neither...if no kind is specified, the node is just a 'null' node - in Blitz3D -speak, a pivot. - -The presence of an ANIM chunk in a NODE indicates that an animation starts here in the hierarchy. -This allows animations of differing speeds/lengths to be potentially nested. - -There are many more 'kind' chunks coming, including camera, light, sprite, plane etc. For now, the -use of a Pivot in cases where the node kind is unknown will allow for backward compatibility. - - - -************************************************************************************ -* Examples * -************************************************************************************ - -A typical b3d file will contain 1 TEXS chunk, 1 BRUS chunk and 1 NODE chunk, like this: - -BB3D - 1 - TEXS - ...list of textures... - BRUS - ...list of brushes... - NODE - ...stuff in the node... - -A simple, non-animating, non-textured etc mesh might look like this: - -BB3D - 1 ;version - NODE - "root_node" ;node name - 0,0,0 ;position - 1,1,1 ;scale - 1,0,0,0 ;rotation - MESH ;the mesh - -1 ;brush: no brush - VRTS ;vertices in the mesh - 0 ;no normal/color info in verts - 0,0 ;no texture coords in verts - {x,y,z...} ;vertex coordinates - TRIS ;triangles in the mesh - -1 ;no brush for this triangle - {v0,v1,v2...} ;vertices - - -A more complex 'skinned mesh' might look like this (only chunks shown): - -BB3D - TEXS ;texture list - BRUS ;brush list - NODE ;root node - MESH ;mesh - the 'skin' - ANIM ;anim - NODE ;first child of root node - eg: "pelvis" - BONE ;vertex weights for pelvis - KEYS ;anim keys for pelvis - NODE ;first child of pelvis - eg: "left-thigh" - BONE ;bone - KEYS ;anim keys for left-thigh - NODE ;second child of pelvis - eg: "right-thigh" - BONE ;vertex weights for right-thigh - KEYS ;anim keys for right-thigh - -...and so on. diff --git a/docs/index.html b/docs/index.html index 28d33e3..c80a569 100644 --- a/docs/index.html +++ b/docs/index.html @@ -60,7 +60,7 @@