====== Water map file ====== The current file format for L3DT water maps is WMF v1.0. This file format is largely based on the [[l3dt:formats:specs:hff|HFF v1.0 format]], but also supports multiple data layers (water level, water type, water ID#). The header structure is as follows: ===== Header structure ===== The water data in the WMF v1.0 file is preceded by a header containing the following information: ^ Field name ^ Contents ^ Length ^ Offset ^ Purpose ^ | ASCII file marker | "L3DT" | 4 | 0 | Tells L3DT and humans that this is an L3DT file. Note string is not null terminated. | | Binary map-type marker | USHORT | 2 | 4 | Tells L3DT what type of map file this is. This must be 600 for WMF v1.0 | | ASCII map-type marker | "WMF_v1.0" | 8 | 6 | Lets humans know what type of file this is. Note string is not null terminated. | | Data offset | USHORT | 2 | 14 | Indicates the address of the first map pixel in this file, relative to the start of the file. [[#Header length & reserved section|See comments below]].| |Map width | UINT | 4 | 16 | East-west extent of the map (number of pixels). | |Map height | UINT | 4 | 20 | North-south extent of the map (number of pixels). | |Water level data size | BYTE | 1 | 24 | Water level data size (bytes per water level value), either 2 or 4. | |Floating point flag | BYTE | 1 | 25 | 1 if depth is stored as floating-point, 0 if integers. | |Vertical scale | float | 4 | 26 | Vertical scale (in metres) of the heightfield. | |Vertical offset | float | 4 | 30 | Vertical offset (in metres) of the heightfield. | |Horizontal scale | float | 4 | 34 | Horizontal scale (in metres) of the heightfield. | |Tile size | USHORT | 2 | 38 | [[l3dt:formats:specs:HFF#b) Tiled order|See 'tiled order' comments for HFF]]. | |Wrap flag | BYTE | 1 | 40 | [[l3dt:formats:specs:HFF#Wrap flag|See 'wrap flag' comments for HFF]]. | |Reserved | BYTE | 1 | 41 | Must be 0. | |Aux. data type | USHORT | 2 | 42 | Identifier for auxiliary pixel data type. | |Aux. data size | BYTE | 1 | 44 | Size in bytes of auxiliary pixel data. | |Reserved | 0 | see below | 45 | [[#Header length & reserved section|See comments below]]. | ===== Header length & reserved section ===== Typically the //data offset// is set to 64, meaning the reserved section is 64 - 45 = 19 bytes long. The reserved section contains no information, but may be used in later versions to store additional parameters, flags, etc. ===== Pixel order ===== Please consult the [[l3dt:formats:specs:hff#pixel_order|Pixel order]] section for the HFF format, from which WMF is derived. ===== Pixel structure ===== Each pixel in the water map file consists of a //water level// section followed by a //auxiliary data// section. ==== Water level data types ==== Depending on the //water level data size// and //floating point flag// values in the file header, WMF water level data may be either: * Single-precision floating point values (32-bit). * Unsigned short integers (16-bit). To convert the file values to real-world water levels (in metres), the WMF format uses the same vertical scaling system as the HFF format. For more information, please refer to the 'reading/writing a HFF' section of the HFF specification ([[http://www.bundysoft.com/docs/doku.php?id=l3dt:formats:specs:hff#reading_a_hff|link here]]). ==== Auxiliary pixel data ==== The contents of the auxiliary pixel data section depends on the value of the //Aux. data type// section in the header. === Auxiliary data type 0 === If the value of //Aux. data type// is 0, there is no auxiliary data. === Auxiliary data type 1 (default) === If the value of //Aux. data type// is 1, then each pixel has three additional bytes following the water level data. These bytes are: ^ Byte ^ Type ^ What is it? ^ | 0 | unsigned byte | The water type ID. Values include 0 (no water), 10 (ocean), 11 (ocean edge), 30 (lake), 31 (lake edge), 90 (water table, below terrain). | | 1-2 | unsigned short | The water body index, which identifies the lake/ocean to which this pixel belongs. Uses Intel byte order. | ===== Source code for reading/writing WMF ===== The source code for L3DT's WMF plugin is [[http://www.bundysoft.com/L3DT/downloads/plugins/src/L3DTio_WMF-src.zip|available here]]. This code is written in C++, using MSVC 7.0 and L3DT's [[http://www.bundysoft.com/docs/doku.php?id=zeolite|Zeolite plugin API]].