Subscribe to News
J2ME : M3G files
Author : Jbuenol
From TechnologicalWiki
Contents |
[edit] Introduction
The Mobile 3D Graphics API, commonly referred to as M3G, is a specification defining an API for writing Java programs that produce 3D computer graphics. It extends the capabilities of the Java Platform, Micro Edition, a version of the Java platform tailored for embedded devices such as mobile phones and PDAs. The object-oriented interface consists of 30 classes that can be used to draw complex animated three-dimensional scenes. The M3G files contain the representation of the components which represent the objects and scenaries of a virtual 3D world. The data of these files are used by the Mobile 3D Graphics API to create a visual representation of the scene.
[edit] MIME Type and File Extension
The MIME type for this file format is application/m3g. The file extension (for systems that do not support MIME type queries) is .m3g, to match the lowest level name in the package hierarchy.
[edit] File Structure
The file consists of the file identifier, followed by one or more sections. Thus the overall file structure looks like this:
| File Identifier | |
| Section 0 | File Header Object |
| Section 1 | External Reference Objects |
| Section 2 | Scene Objects |
| ... | ... |
| Section n | Scene Objects |
The reason for having different sections is that some of the objects, such as the mesh objects, should be compressed to reduce file size, whereas other objects, such as the header object, should not be compressed. The header object must be kept uncompressed since it should be easy to read quickly.
- The first section, Section 0, must be present, must be uncompressed and must contain only the header object. This object contains information about the file as a whole.
- If there are external references in the file, then these must all appear in a single section immediately following the header section. This section may be compressed or uncompressed. External references allow scenes to be built up from a collection of separate files.
- Following these are an unspecified number of sections containing scene objects.
The file must contain the header section, plus at least one other non-empty section (containing at least one object). It is possible to have a file consisting solely of external references, or solely of scene objects.
Note : "A file containing no objects at all is not a valid M3G file, and must be treated as an error".
[edit] File Sections
A section is a data container for one or more objects. The section header determines if the objects are compressed or not, how much object data there is, and also contains a checksum. In this document, we will talk about "sections that are compressed" and "sections that are uncompressed". In reality, we will mean "sections where the objects are compressed", and "sections where the objects are uncompressed".
Each section has the following structure:
Byte CompressionScheme : tells how the Objects field in this section is compressed.
UInt32 TotalSectionLength : This is the total length of the section in bytes; from the start of this section to the start of the next section.
- UInt32 UncompressedLength : Knowing the size of the decompressed data.
- Byte[] Objects : The objects in each section are serialized as an array of bytes, one after the other. If it is compressed, it is compressed as a single chunk of data, not as separate objects.
- UInt32 Checksum : To be able to verify that the section was correctly loaded, there is a 32-bit checksum of all the data in the section.
We will now go through the individual parts of the section.
[edit] Object Structure
The object data stored in each section is first decompressed and then interpreted as a sequence of objects. This separates the act of decompression from the interpretation of the data. All data documented in this section is assumed already to be in its uncompressed form. Each object in the file represents one object in the scene graph tree, and is stored in a chunk. The structure of an object chunk is as follows:
- Byte ObjectType : This field describes what type of object has been serialized. For instance, we could have a Camera node, a Mesh node or a Texture2D object.
- UInt32 Length : This contains the length of the Data array, in bytes. Note that a value of 0 in this field may be legal; some objects require no additional data over and above their mere presence.
- Byte[] Data : This is data that is specific for the object. It is up to the loader to interpret this data according to the object type and populate the object accordingly.
[edit] Object Ordering
All the objects in the scene graph are serialized in leaf-first order, or reference based order as it is also called. Before serializing a specific object, all other objects referenced by that object must already have been serialized. Objects may refer to themselves if this is allowed by the scene data structures.
By definition, the root of the tree will be sent last.
For output, it is possible to use a "leaves first" strategy - start by serializing all the objects that do not reference other objects, and then all the objects that refer to the objects already sent, and so it continues until all objects are sent.
[edit] Object Data
There are 2 kinds of object in M3G, The objects which class belongs to the API, and the special objects which purpose is specific.
[edit] Special Object Data
- Header Object : There must be exactly one Header object in a file, and it must be the only object in the first section of the file, which in turn must be uncompressed. Due to its position in the file, it will always be assigned object index 1.
Byte[2] VersionNumber
Boolean hasExternalReferences
UInt32 TotalFileSize
UInt32 ApproximateContentSize
String AuthoringField
- External Reference : Instead of storing an object in-place, it is possible to have an external reference, in the form of a URI. This is stored in the object data as a single, nul-terminated UTF-8 string. Relative URIs are relative to the file in which they are found, as usual. For example, a URI of "http://www.gamesforfun.com/objs/redcar.m3g", indicates another file in the M3G file format, at an absolute address, and "bluecartexture.png" indicates a PNG file in the same location as the current file.
String URI
[edit] Per-Class Data
This section describes the data for each class in the API. Where a class is a subclass, the superclass's data is always output first, and this information is taken to be part of the data for the class as a whole.
Detailed information about each field is not given - it should be assumed that the data have the same meanings as those assigned in the API.
Any values which would be invalid as arguments to the corresponding methods in the API are also invalid in the file and must be reported as errors. For example, a negative value in the light attenuation fields is disallowed by the API and is therefore also disallowed in the file format.
[edit] ObjectType Values and API Objects description
| ObjectType | value Object Type | ObjectType | value Object Type |
| 00 | Header Object | 13 | Material |
| 01 | AnimationController | 14 | Mesh |
| 02 | AnimationTrack | 15 | MorphingMesh |
| 03 | Appearance | 16 | SkinnedMesh |
| 04 | Background | 17 | Texture2D |
| 05 | Camera | 18 | Sprite |
| 06 | CompositingMode | 19 | KeyframeSequence |
| 07 | Fog | 20 | VertexArray |
| 08 | PolygonMode | 21 | VertexBuffer |
| 09 | Group | 22 | World |
| 10 | Image2D | 23...254 | Reserved future versions |
| 11 | TriangleStripArray | 255 | External Reference |
| 12 | Light |
