Difference between revisions of "AC4F8687"

Latest revision as of 18:03, 17 September 2012

The Geometry Data Container format is the 3D mesh of The Sims 2 files. GMDC is part of the SceneGraph Resource Collection set of files, more commonly known as RCOL. This complex file format stores information such as vertices, normal vectors, UV texture mapping coordinates, and bone joints, and morphs. It is a very important file to modding efforts, as its central to creating new objects in the game.

The file specification for GMDC follows. The format uses the standard RCOL file header, and data chunks conform to the standard RCOL chunk header structure. This definition also exists as GMDC_Data_Structure.

[edit] The File Structure

REF		reference: RCOL file header and index

; Depending on the RCOL index, other RCOL chunks 
; may appear before the GMDC chunk

7BITSTR		block name (cGeometryDataContainer)
DWORD		block ID
DWORD		block version

REF		reference: read a cSGResource chunk here

REF		reference: Elements section (P1)
REF		reference: Linkages section (P2)
REF		reference: Groups section   (P3)
REF		reference: Model section    (P4)
REF		reference: Subsets section  (P5)

; Depending on the RCOL index, other RCOL chunks
; may appear after the GMDC chunk

[edit] The Elements (P1) Section

The first section of a GMDC file is the Elements chunk. This section stores the actual vertices, normals, UV coordinates, morphs, etc.

DWORD		element count		; 32bit count

; Elements
LOOP					; repeat previous value times
  DWORD		References Array Size	; Size of element array that can be referenced in Referenced Array List
  DWORD		Element Identity	; See table 1 below
  DWORD		Identity repetition	; logs how many times this identity has been used

  DWORD		Block Format		; Determines the format of the element values list
  DWORD		Set Format		; Determines the format of values in the element list

; Element Value List block
  DWORD		Block size		; The size of the following data block in bytes

  LOOP		element value list	; repeat by formula 1 below
	LOOP	value set		; repeat by formula 2 below
	  IF (GMDC version = 4)
	    WORD				; Single value from a value set
	  ELSE IF (GMDC version < 4)
	    DWORD				; Single value from a value set
	ENDLOOP
  ENDLOOP

; Reference Array  (links to entries by references# in another element - generally automatic associations)

  DWORD count
  LOOP      ; repeat previous count value times
	IF (GMDC version = 4)
	  WORD				; Single Reference Array Entry
	ELSE IF (GMDC Version < 4)
	  DWORD				; Single Reference Array Entry
  ENDLOOP
ENDLOOP

[edit] Table 1 : Element Identities

NOTE: 0xDB830795 may not be UV Coordinate deltas. As used in EP4 (Pets) these blocks contain 4-byte collections (one per vertex) that contain a limited set of bytes like 0x00, 0x01 and 0xff. Perhaps these are flags related to the UVs.

[edit] Table 2: Block Formats

[edit] Table 3: Set Groups (formats)

[edit] Reading the element value list

To read the element value list, use the following code:

'' Read blockFormat
'' ...

'' Determine set length
int setLength = 1;
switch (blockFormat)
{
  case 0x00: 
  case 0x04:
	setLength = 1:
	break;
  case 0x01:
	setLength = 2;
	break;
  case 0x02:
	setLength = 3;
	break;
}

'' Determine list length
int listLength = blockSize / setLength / 4;

'' Read list
for (int i=0; i<listLength; i++)
{
  '' Read single set
  for (int j=0; j<setLength; j++)
  {
	if (blockFormat == 0x04)
	{
	 	'' Read a 32bit integer
	}
	else
	{
	'' Read a float
	}
  }
}

The "Target Indices" sections only appear in the Elements section, and flag the inclusion of Morph Vertex Deltas, (optionally) Morph Normal Deltas and a Morph map for one or more subsequent group. For multiple morph models, there would be 'n' Morph Delta sections, then (optionaly) 'n' Morph normals sections, then a single morph map, which is mapped into sets of 4 bytes. Each TargetIndex usually matches with a name pair, but the name pair is where the game finds tehmorph from. The index value may be zero, if the first target is named. For each group with a morph map there may be as many as four Morph Vertex Deltas. Each of these corresponds to one byte from the Morph Map. It is possible to have a large number of morphs which are spread in a fashion where no more than four are in a Morph Map, or there may be many more than four, but arranged such that each vertex has no more than four deltas. Regardless of how many morphs are there, the relationship is that you walk through the Morph Map one longword at a time, pulling the four bytes. If Morph 'n' is located in the least significant byte, then the deltas for it to be applied to the vertex position will come from the first Morph Vertex Delta Array in that section. However, if it was located in the next-significant position, it would be pulled from the second Morph Vertex Delta Array.

Since Zero may be a valid morph value (depending on whether it is named), a morph map of all zeroes may indicate a valid morph.

[edit] The Linkages (P2) Section

The second section in a GMDC contains data to link elements from section one, to groupings of those elements, defined in section 3 (P3). In some cases, three additional blocks other than the main index may be populated. These blocks contain extra indices of vertices, normals, and UV's for a subset mesh, defined later on in section 5 (P5).

DWORD		count
LOOP					; repeat "previous count" times
  DWORD		index count
  LOOP					; index, Block A
	IF (GMDC Version = 4)
	  WORD	index value
	ELSE IF (GMDC version < 4)
	  DWORD	index value
  ENDLOOP

  DWORD		referenced array size (max element reference array size)
  DWORD		active elements for this link (active element #'s)

  DWORD		Submodel vertex count	
  LOOP					; Block B
	IF (GMDC Version = 4)
	  WORD	subset index value
	ELSE IF (GMDC version < 4)
	  DWORD	subset index value
  ENDLOOP

  DWORD		Submodel normals count	
  LOOP					; Block C
	IF (GMDC Version = 4)
	  WORD	normals index value
	ELSE IF (GMDC version < 4)
	  DWORD	normals index value
  ENDLOOP

  DWORD		Submodel UV count		
  LOOP					; Block D
	IF (GMDC Version = 4)
	  WORD	UV index value
	ELSE IF (GMDC version < 4)
	  DWORD	UV index value
  ENDLOOP
ENDLOOP

[edit] The Groups (P3) Section

The third section in GMDC is the groups section. Groups collect elements from section one, through linkages in section 2, to form components like faces of a mesh.

DWORD		count
LOOP					; repeat "previous count" times
  DWORD		primitive type
  DWORD		link index

  7BITSTR	name of object

  DWORD		face count
  LOOP					; Array of vertices that make the faces.  Items are read sequentially in groups of three to form a face. Repeat "face count" times
	IF (GMDC version = 4)
	  WORD	vertex reference
	ELSE IF (GMDC version < 4)
	  DWORD	vertex reference
  ENDLOOP 

  DWORD		opacity amount		; 0xFFFFFFFF = full opacity, 0x0 = full transparency, < 16 for shadows

  IF (GMDC version != 1)
	DWORD	subset count
	LOOP				; repeat "subset count" times
	  IF (GMDC version = 4)
	    WORD	model subset reference
	  ELSE IF (GMDC version < 4)
	    DWORD	model subset reference
	ENDLOOP
ENDLOOP

The last subset version maps the value used in the 0xFBD70111 (Bone Assignments) section to the standard values used by other parts of the game. For example, a bone value of 4 (from P1) would be used as an index to retrieve a value from the fifth element of this array that represents the real bone number, as used in other parts of the game. In creating a new GMDC the value of subset count should be exactly the same as the number of bones actually referenced by the group.

[edit] The Model (P4) Section

There is only one model per GMDC, so the next section does not have an outer loop. The model contains information to rotate and transform the mesh, as well as a bounding mesh for the whole model. The mesh stored in the model section is composed of vertices and the faces formed with them. In the face list, each sequential set of 3 values represents a face. The face is defined by using the vertices at the positions in the vertex list specified in the 3 face values.

DWORD		transform block count
LOOP					; repeat "transform block count" times
  DWORD		quaternion x		; Rotation quaternion: x plane amount
  DWORD		quaternion y		; Rotation quaternion: y plane amount
  DWORD		quaternion z		; Rotation quaternion: z plane amount
  DWORD		quaternion w		; Rotation quaternion: focal point

  DWORD		transform x		; Transform: x amount
  DWORD		transform y		; Transform: y amount
  DWORD		transform x		; Transform: z amount
ENDLOOP

DWORD		name pairs count
LOOP					; repeat "name pairs count" times (this is equal to the number of targets located in P1 (the first target is usually a pair of NULL names).
  7BITSTR	blend group name
  7BITSTR	assigned element name
ENDLOOP

DWORD		vertex count		; if zero, no mesh, continue to next section (used when model has no bones or joints)
IF (vertex count > 0)
  DWORD		face count

  LOOP					; repeat "vertex count" times
	DWORD	vertex x
	DWORD	vertex y
	DWORD	vertex z
  ENDLOOP

  LOOP					; repeat "face count" times
	IF (GMDC version = 4)
	  WORD
	ELSE IF (GMDC version < 4)
	  DWORD
  END LOOP

You can reduce the resultant size if this part by consolidating duplicate vertices (since normals and UVs are not elements), as long as you adjust the correct index value in the face reference list.

The "Name Pairs" are used by the game to identify links to the morphs for animation purposes. Inclusion of full morph data without duplicating the name pairs referenced by the animations will not render.

[edit] The Subset (P5) Section

Subsets are parts of the full mesh, and are associated with bones (joints) and other components of the model.

DWORD           subset count  ; a standard Sims2 skeleton has 65 joints, although many are not used by the vertices. Other values indicate animated meshes with joint or target areas, but are processed in the same manner.
LOOP            ; repeat 'subset count' times
  DWORD		vertex count		; if zero, blank section
  IF (vertex count > 0)
	DWORD		face count
	
	LOOP					; repeat "vertex count" times
  	DWORD	vertex x
	DWORD	vertex y
	DWORD	vertex z
	ENDLOOP

	LOOP					; repeat "face count" times
  	IF (GMDC version = 4)
	  WORD
	ELSE IF (GMDC version < 4)
	  DWORD
	END LOOP
END LOOP

[edit] Reading the GMDC

[edit] Geometry

To read the geometry, you start with the group. From the link indexed in the group, you read the elements. The vertex list element is the position of the vertices. The face list in the P3(groups) is an array of vertices read in groups of 3 to form faces. The normals element is a list of normal vectors for the vertices. Texture map coordinates stored in a referenced element as well(in [U,V]). These are all standard elements of a group, but bumpmap normals may also be present(mostly body meshes).

[edit] Blends

The Blends are defined in the models section and used in animations. Blend zero alot of times seems to be null, but actually is just as valid as the others(although all of its vertices may have 0.0 deltas). For Each blend, there may be a target index element (although the target index may be empty). While most meshes only have 1 or 2 blends, there are some like the Sim face mesh that have 27.

A Morph is a change in a vertex (position, normals, UV coords, and/or bumpmaps). There can be up to four of them per vertex

The Morph Map element maps Blend ids to the Morph elements. The rows are vertices, columns are Morphs Vertex Data section (up to 4 per vertex element), and values are blends. No matter how many blends are present(even with the face at 27) there is no more than one map per group (subset).

This article is imported from the old MTS2 wiki. It's original page, with comments, can be found at http://old_wiki.modthesims2.com/AC4F8687