Burnout Wiki:Format documentation specification: Difference between revisions
Burnout Wiki:Format documentation specification (view source)
Revision as of 07:16, 4 August 2023
, 9 months agoBurninrubber0 moved page Burnout Wiki:Format documentation guide to Burnout Wiki:Format documentation specification
(Finish enumerations section.) |
m (Burninrubber0 moved page Burnout Wiki:Format documentation guide to Burnout Wiki:Format documentation specification) |
||
| (11 intermediate revisions by the same user not shown) | |||
Line 5:
Much of the time, the exact data type of a field is unknown even when its meaning and purpose are clear. A 4-byte integer could be signed or unsigned and it could be an int, int32_t, long, DWORD, or any number of other types. In these cases, fixed-width data types as defined in [https://cplusplus.com/reference/cstdint/ the C++ header stdint.h] should be used. Where the sign is unclear, choose the unsigned variant of the type.
In cases where the type is truly unknown (e.g., it cannot be discerned whether it is a float or integer), a single question mark may be
== Endianness ==
The byte order, or [https://en.wikipedia.org/wiki/Endianness endianness], of hexadecimal values displayed on the wiki should always be big endian. If they are little endian as they are on PC, PS2, and Xbox, they should be converted (byteswapped).
== Unused columns ==
Columns defined here should never be removed, even when empty. This is a compromise between readability and editability; adding columns, especially in large tables, can be very tedious and time-consuming.
== Sections ==
Formats should be documented with at least the top-level section ''Structures''. ''Unions'', ''Typedefs'' and ''Enumerations'' are optional top-level sections. Other top-level sections may be added as necessary.
Generally, individual structures, unions, typedefs, and enumerations are third-level sections while variants (such as 32 and 64 bit) are fourth-level. While this page structure is preferred, it is not a strict requirement; all lower-level sections may be chosen at the editor's discretion.
Sections should be named the full name of the type with all namespaces included, e.g., BrnVehicle::GraphicsSpec. If the full name is unknown, use a name relevant to its purpose. Never title a section "unknown" unless the content's purpose is truly unknown.
== Page names ==
Page names should be plain English versions of the official format name, e.g., the page for GenericRwacWaveContent is titled Generic RWAC Wave Content. If the format name is unknown, use a name most relevant to its purpose.
= Structures =
Line 34 ⟶ 47:
==== Type ====
The data type of the field. If the type is unknown, refer to [[#Choosing a data type
If the type is known and is a structure, union, enumeration, or custom typedef, this should be a link to the relevant section. If the official documentation states it is a standard type but it is still used as an enumerated value or similar, leave the link in the Comments column in the style "See <nowiki>[[link]]</nowiki>".
This column may be left blank if the area is known to be undefined (padding).
==== Name ====
The name of the field. This must be provided in some official capacity, such as source code, debugging symbols, or online documentation. If no official documentation is available,
This column may be left blank if the area is known to be undefined (padding).
Line 50 ⟶ 63:
User-defined types should not be described here; instead, they should be linked to from the Type column and described there. This column is solely for describing the field's use(s).
If nothing is known about the field, this column may be left blank
==== Comments ====
Any comments about the field may be left here. This includes example values, whether the field has a constant value in all samples (such as it being null), and other speculation on it that does not fit the Description column. This is also where certain types, such as untyped enumerations, may be linked to in the style "See <nowiki>[[link]]</nowiki>".
If there are no additional comments, this column may be left blank
= Unions =
Unions are types which use only one member at a time. They can be displayed similarly to structures but without the offset field.
{| class="wikitable"
|-
! Length !! Type !! Name !! Description !! Comments
|-
| 0x4 || uint32_t || mExampleInt || An integer member. || This is an example
|-
| 0x4 || float || mExampleFloat || A floating point member. || This is an example
|}
== Columns ==
==== Length ====
The length of the field. This should always be hexadecimal and prefixed with <code>0x</code>, even if the length is less than decimal 10. See [[#Length|Structures]] for more details.
The length should be defined per member just as it is with structures. The overall length of the type will be determined by its largest member and should not be listed separately.
==== Type ====
The data type of the field. If the type is unknown, refer to [[#Choosing a data type|choosing a data type]].
If the type is known and is a structure, union, enumeration, or custom typedef, this should be a link to the relevant section. If the official documentation states it is a standard type but it is still used as an enumerated value or similar, leave the link in the Comments column in the style "See <nowiki>[[link]]</nowiki>".
This column may be left blank if the area is known to be undefined (padding).
==== Name ====
The name of the field. This must be provided in some official capacity, such as source code, debugging symbols, or online documentation. If no official documentation is available, display a single question mark to mark it as unknown.
This column may be left blank if the area is known to be undefined (padding).
==== Description ====
A description of the field's meaning and/or purpose as defined by either official documentation, the user, or some combination of both.
User-defined types should not be described here; instead, they should be linked to from the Type column and described there. This column is solely for describing the field's use(s).
If nothing is known about the field, this column may be left blank.
==== Comments ====
Any comments about the field may be left here. This includes example values, whether the field has a constant value in all samples (such as it being null), and other speculation on it that does not fit the Description column. This is also where certain types, such as untyped enumerations, may be linked to in the style "See <nowiki>[[link]]</nowiki>".
If there are no additional comments, this column may be left blank.
= Typedefs =
Typedefs are unique in that they can only be detected when some form of official documentation is available. This means there are no unknowns associated with them
Type definitions should be displayed in the following format:
{| class="wikitable"
|-
! Name !! Type !! Length !! Comments
|-
| ExampleType || int32_t || 0x4 || This is just an example
|}
Line 74 ⟶ 129:
==== Type ====
The type specifier used with the typedef.
==== Length ====
The length of the type in bytes. This should be a hexadecimal value prefixed with <code>0x</code>.
==== Comments ====
A description of the typedef may be provided here, as well as any additional comments.
If there are no additional comments, this column may be left blank
= Enumerations =
Line 86 ⟶ 144:
== Traditional enumerations ==
Most enumerations are sets of sequential values from which a single value may be used per variable. It follows that such enumerations are typically in decimal format, and wiki content should reflect this. Sometimes, however, it is appropriate to use hexadecimal, such as with how [[Resource Types
Enumerations should be displayed in the following format:
Line 97 ⟶ 155:
| EXAMPLE_ENUM_ONE || 1 || An example with the value 1.
|-
| EXAMPLE_ENUM_FORCE_INT || 0x7FFFFFFF || Forces the enum to compile to a 32-bit int.
|}
== Binary flags ==
Flags allow multiple options to be selected in a single enumeration by way of making each bit a flag. Because of this, there are multiple ways to specify their values
Binary flags should be displayed in the following format:
Line 119 ⟶ 177:
== Columns ==
==== Name ====
The name of the enumerated value. This must be from official documentation. If no official documentation is available,
==== Value ====
Line 127 ⟶ 185:
Any description or additional comments related to the enumerated values may be provided here.
If there are no additional comments, this column may be left blank
= Bit fields =
[https://en.wikipedia.org/wiki/Bit_field Bit fields] should be denoted in a similar manner to [[#Structures|structures]] and should be listed under the same top-level section. There are, however, some important differences to note.
{| class="wikitable"
|-
! Offset (bits) !! Length (bits) !! Name !! Description !! Comments
|-
| 0 || 4 || exampleFourBitField || An example field starting at bit 0 extending for 4 bits. || This is just an example
|}
== LSB 0 vs MSB 0 ==
As with [[#Binary flags|flags]], the generally accepted standard is to document binary structures in LSB 0 notation; that is, the least significant bit is listed first. However, this only readable when said structure is split evenly along byte boundaries such as in [[Texture/Xbox 360#GPUTEXTURE_FETCH_CONSTANT|Xbox 360 textures]]. In structures such as [[Generic RWAC Wave Content#Header|SndPlayer assets]], the structure can be difficult to read when reversed and is actually defined in MSB 0 in the source code.
This solution used by the wiki is to display all binary structures in MSB 0 notation, even when official documentation has it in LSB 0. This improves consistency and readability.
== Examples ==
Binary structures can be far more confusing than normal structures. Thus, though not required, an example is always helpful.
These are created by listing each bit as a column in the header row, the parsed value of the bits in the second row, and a brief description of the parsed data in the third row. The <code>colspan</code> tag can be used to merge columns. The caption, if present, should state the hexadecimal code for the bits.
The following is an example of a bit field header structure for a larger asset:
{| class="wikitable"
|-
! Offset (bits) !! Length (bits) !! Name !! Description !! Comments
|-
| 0 || 4 || version || Example version ||
|-
| 4 || 12 || size || Example size ||
|-
| 16 || 4 || numElements || Example number of elements ||
|-
| 20 || 4 || assetIndex || Example asset index ||
|-
| 24 || 8 || elementSize || Example size of elements in the bit field ||
|}
And some example data:
{| class="wikitable"
|+ Hex: 16 56 33 A8
|-
! Bit value !! 0 !! 0 !! 0 !! 1 !! 0 !! 0 !! 0 !! 1 !! 1 !! 1 !! 1 !! 1 !! 1 !! 1 !! 0 !! 0
|-
| '''Parsed value''' || colspan=4|1 || colspan=12|0x1FC
|-
| '''Description''' || colspan=4|Version 1 || colspan=12|Total asset size of 0x1FC
|}
Should a bit field's table extend past the default width of the default skin (960px), it should be split at the last field before that width and a new table should be started below the first with the first column being ''(cont.)''.
{| class="wikitable"
|-
! rowspan=3|(cont.) !! 0 !! 0 !! 1 !! 1 !! 0 !! 0 !! 1 !! 1 !! 1 !! 0 !! 1 !! 0 !! 1 !! 0 !! 0 !! 0
|-
| colspan=4|3 || colspan=4|3 || colspan=12|0xA8
|-
| colspan=4|3 total elements in this asset || colspan=4|Asset index 3 || colspan=12|Each element has a size of 0xA8
|}
== Columns ==
==== Offset ====
The bit index of the field. This should always be in base 10.
==== Length ====
The number of bits the field uses. This should always be in base 10.
==== Name ====
The name of the field. This must be provided in some official capacity, such as source code, debugging symbols, or online documentation. If no official documentation is available, display a single question mark to mark it as unknown.
This column may be left blank if the area is known to be undefined (padding).
==== Description ====
A description of the field's meaning and/or purpose as defined by either official documentation, the user, or some combination of both.
If nothing is known about the field, this column may be left blank.
==== Comments ====
Any comments about the field may be left here. This includes example values, whether the field has a constant value in all samples (such as it being null), and other speculation on it that does not fit the Description column.
If there are no additional comments, this column may be left blank.
| |||