dsf.h File Reference

#include <stdlib.h>
#include <stdint.h>
#include "avl.h"
#include "list.h"

Include dependency graph for dsf.h:

Go to the source code of this file.

Data Structures
struct	dsf_prop_t
struct	dsf_prop_atom_t
struct	dsf_demi_atom_t
struct	dsf_planar_atom_t
struct	dsf_atom_t
struct	dsf_t
struct	dsf_lookup_t
struct	dsf_cmd_parser_t
struct	dsf_idx_rng_arg_t
struct	dsf_indices_arg_t
struct	dsf_indices_xpool_arg_t
struct	dsf_poly_arg_t
struct	dsf_poly_rng_arg_t
struct	dsf_flags_n_lod_arg_t
struct	dsf_comment_arg_t

Macros
#define	DSF_ATOM(a, b, c, d)   (((a) << 24) | ((b) << 16) | ((c) << 8) | (d))
#define	DSF_ATOM_HEAD   DSF_ATOM('H', 'E', 'A', 'D')
#define	DSF_ATOM_PROP   DSF_ATOM('P', 'R', 'O', 'P')
#define	DSF_ATOM_DEFN   DSF_ATOM('D', 'E', 'F', 'N')
#define	DSF_ATOM_TERT   DSF_ATOM('T', 'E', 'R', 'T')
#define	DSF_ATOM_OBJT   DSF_ATOM('O', 'B', 'J', 'T')
#define	DSF_ATOM_POLY   DSF_ATOM('P', 'O', 'L', 'Y')
#define	DSF_ATOM_NEWT   DSF_ATOM('N', 'E', 'T', 'W')
#define	DSF_ATOM_DEMN   DSF_ATOM('D', 'E', 'M', 'N')
#define	DSF_ATOM_GEOD   DSF_ATOM('G', 'E', 'O', 'D')
#define	DSF_ATOM_POOL   DSF_ATOM('P', 'O', 'O', 'L')
#define	DSF_ATOM_SCAL   DSF_ATOM('S', 'C', 'A', 'L')
#define	DSF_ATOM_PO32   DSF_ATOM('P', 'O', '3', '2')
#define	DSF_ATOM_SC32   DSF_ATOM('S', 'C', '3', '2')
#define	DSF_ATOM_DEMS   DSF_ATOM('D', 'E', 'M', 'S')
#define	DSF_ATOM_DEMI   DSF_ATOM('D', 'E', 'M', 'I')
#define	DSF_ATOM_DEMD   DSF_ATOM('D', 'E', 'M', 'D')
#define	DSF_ATOM_CMDS   DSF_ATOM('C', 'M', 'D', 'S')
#define	DSF_ATOM_ID_PRINTF(atom)

Typedefs
typedef void(*	dsf_cmd_cb_t) (dsf_cmd_t cmd, const void *cmd_args, const dsf_cmd_parser_t *parser)

Enumerations
enum	{ DSF_REASON_SZ = 256 }
enum	dsf_data_type_t {   DSF_DATA_SINT16 , DSF_DATA_UINT16 , DSF_DATA_SINT32 , DSF_DATA_UINT32 ,   DSF_DATA_SINT64 , DSF_DATA_UINT64 , DSF_DATA_FP32 , DSF_DATA_FP64 }
enum	dsf_data_plane_enc_t { DSF_ENC_RAW = 0 , DSF_ENC_DIFF = 1 << 0 , DSF_ENC_RLE = 1 << 1 }
enum	{   DEMI_DATA_FP32 = 0 , DEMI_DATA_SINT = 1 , DEMI_DATA_UINT = 2 , DEMI_DATA_MASK = 3 ,   DEMI_POST_CTR = 1 << 2 }
enum	dsf_cmd_t {   DSF_POOL_SEL , DSF_JUNCT_OFFSET_SEL , DSF_SET_DEFN8 , DSF_SET_DEFN16 ,   DSF_SET_DEFN32 , DSF_ROAD_SUBTYPE , DSF_OBJ , DSF_OBJ_RNG ,   DSF_NET_CHAIN , DSF_NET_CHAIN_RNG , DSF_NET_CHAIN32 , DSF_POLY ,   DSF_POLY_RNG , DSF_NEST_POLY , DSF_NEST_POLY_RNG , DSF_TERR_PATCH ,   DSF_TERR_PATCH_FLAGS , DSF_TERR_PATCH_FLAGS_N_LOD , DSF_PATCH_TRIA , DSF_PATCH_TRIA_XPOOL ,   DSF_PATCH_TRIA_RNG , DSF_PATCH_TRIA_STRIP , DSF_PATCH_TRIA_STRIP_XPOOL , DSF_PATCH_TRIA_STRIP_RNG ,   DSF_PATCH_TRIA_FAN , DSF_PATCH_TRIA_FAN_XPOOL , DSF_PATCH_TRIA_FAN_RNG , DSF_COMMENT8 ,   DSF_COMMENT16 , DSF_COMMENT32 , NUM_DSF_CMDS }

Functions
dsf_t *	dsf_init (const char *filename)
dsf_t *	dsf_parse (uint8_t *buf, size_t bufsz, char reason[DSF_REASON_SZ])
void	dsf_fini (dsf_t *dsf)
char *	dsf_dump (const dsf_t *dsf)
const dsf_atom_t *	dsf_lookup (const dsf_t *dsf,...)
const dsf_atom_t *	dsf_lookup_v (const dsf_t *dsf, const dsf_lookup_t *lookup)
const dsf_atom_t *	dsf_iter (const dsf_atom_t *parent, uint32_t atom_id, const dsf_atom_t *prev)
bool_t	dsf_parse_cmds (const dsf_t *dsf, dsf_cmd_cb_t user_cbs[NUM_DSF_CMDS], void *userinfo, char reason[DSF_REASON_SZ])
const char *	dsf_cmd2str (dsf_cmd_t cmd)

Detailed Description

This file holds a general-purpose DSF parser. To start parsing a DSF file on disk, use dsf_init() to obtain a handle to the file. When you are done with the DSF file, use dsf_fini() to release the handle.

Definition in file dsf.h.

Macro Definition Documentation

DSF_ATOM

#define DSF_ATOM	(		a,
			b,
			c,
			d
	)		(((a) << 24) | ((b) << 16) | ((c) << 8) | (d))

Definition at line 45 of file dsf.h.

DSF_ATOM_CMDS

#define DSF_ATOM_CMDS   DSF_ATOM('C', 'M', 'D', 'S')

Definition at line 67 of file dsf.h.

DSF_ATOM_DEFN

#define DSF_ATOM_DEFN   DSF_ATOM('D', 'E', 'F', 'N')

Definition at line 50 of file dsf.h.

DSF_ATOM_DEMD

#define DSF_ATOM_DEMD   DSF_ATOM('D', 'E', 'M', 'D')

Definition at line 65 of file dsf.h.

DSF_ATOM_DEMI

#define DSF_ATOM_DEMI   DSF_ATOM('D', 'E', 'M', 'I')

Definition at line 64 of file dsf.h.

DSF_ATOM_DEMN

#define DSF_ATOM_DEMN   DSF_ATOM('D', 'E', 'M', 'N')

Definition at line 56 of file dsf.h.

DSF_ATOM_DEMS

#define DSF_ATOM_DEMS   DSF_ATOM('D', 'E', 'M', 'S')

Definition at line 63 of file dsf.h.

DSF_ATOM_GEOD

#define DSF_ATOM_GEOD   DSF_ATOM('G', 'E', 'O', 'D')

Definition at line 57 of file dsf.h.

DSF_ATOM_HEAD

#define DSF_ATOM_HEAD   DSF_ATOM('H', 'E', 'A', 'D')

Definition at line 47 of file dsf.h.

DSF_ATOM_ID_PRINTF

#define DSF_ATOM_ID_PRINTF

(

atom

)

Value:

    ((atom)->id & 0xff000000) >> 24, \
    ((atom)->id & 0xff0000) >> 16, \
    ((atom)->id & 0xff00) >> 8, \
    ((atom)->id & 0xff)

Definition at line 71 of file dsf.h.

DSF_ATOM_NEWT

#define DSF_ATOM_NEWT   DSF_ATOM('N', 'E', 'T', 'W')

Definition at line 54 of file dsf.h.

DSF_ATOM_OBJT

#define DSF_ATOM_OBJT   DSF_ATOM('O', 'B', 'J', 'T')

Definition at line 52 of file dsf.h.

DSF_ATOM_PO32

#define DSF_ATOM_PO32   DSF_ATOM('P', 'O', '3', '2')

Definition at line 60 of file dsf.h.

DSF_ATOM_POLY

#define DSF_ATOM_POLY   DSF_ATOM('P', 'O', 'L', 'Y')

Definition at line 53 of file dsf.h.

DSF_ATOM_POOL

#define DSF_ATOM_POOL   DSF_ATOM('P', 'O', 'O', 'L')

Definition at line 58 of file dsf.h.

DSF_ATOM_PROP

#define DSF_ATOM_PROP   DSF_ATOM('P', 'R', 'O', 'P')

Definition at line 48 of file dsf.h.

DSF_ATOM_SC32

#define DSF_ATOM_SC32   DSF_ATOM('S', 'C', '3', '2')

Definition at line 61 of file dsf.h.

DSF_ATOM_SCAL

#define DSF_ATOM_SCAL   DSF_ATOM('S', 'C', 'A', 'L')

Definition at line 59 of file dsf.h.

DSF_ATOM_TERT

#define DSF_ATOM_TERT   DSF_ATOM('T', 'E', 'R', 'T')

Definition at line 51 of file dsf.h.

Typedef Documentation

dsf_cmd_cb_t

typedef void(* dsf_cmd_cb_t) (dsf_cmd_t cmd, const void *cmd_args, const dsf_cmd_parser_t *parser)

Definition at line 262 of file dsf.h.

Enumeration Type Documentation

anonymous enum

anonymous enum

Definition at line 69 of file dsf.h.

anonymous enum

anonymous enum

Definition at line 104 of file dsf.h.

dsf_cmd_t

enum dsf_cmd_t

Definition at line 169 of file dsf.h.

dsf_data_plane_enc_t

enum dsf_data_plane_enc_t

Definition at line 88 of file dsf.h.

dsf_data_type_t

enum dsf_data_type_t

Definition at line 77 of file dsf.h.

Function Documentation

dsf_cmd2str()

const char * dsf_cmd2str

(

dsf_cmd_t

cmd

)

Utility function to translate a DSF command type into a human-readable description.

Definition at line 1152 of file dsf.c.

dsf_dump()

char * dsf_dump

(

const dsf_t *

dsf

)

Generates a human-readable description of the contents of a DSF file.

Parameters

dsf	The DSF file to describe.

Returns

A NUL-terminated string describing the DSF file. The caller is reponsible for freeing this string using lacf_free().

Definition at line 922 of file dsf.c.

dsf_fini()

void dsf_fini

(

dsf_t *

dsf

)

Destroys a DSF file handle which was previously created using either dsf_init() or dsf_parse().

Definition at line 786 of file dsf.c.

dsf_init()

dsf_t * dsf_init

(

const char *

filename

)

Reads a DSF file from disk and provides a handle to it. This function should be used as the first step to access the DSF data. If the file is compressed on disk, it is decompressed in memory first.

Parameters

filename

The full file name & path to the DSF file on disk.

Returns

A handle to the open DSF file, if successful. If there was a failure in reading the file, this returns NULL instead. The reason for the failure is automatically reported using logMsg().

Definition at line 173 of file dsf.c.

dsf_iter()

const dsf_atom_t * dsf_iter	(	const dsf_atom_t *	parent,
		uint32_t	atom_id,
		const dsf_atom_t *	prev
	)

Iterator to allow you to traverse a list of subatoms of a DSF atom.

Parameters

parent	The parent atom to use as the root of the iteration. We iterate through this atom's subatoms.
atom_id	Atom ID to filter out. This function skips subatoms which do not have an ID which matches this atom.
prev	The previous atom in the iteration. On first call, you should pass a NULL here, to initialize the search.

Returns

The next subatom inside of parent which matches the atom_id. If no matching subatoms are present in the parent, returns NULL.

Example of iterating through all subatoms matching a particular ID:

for (const dsf_atom_t *subatom = dsf_iter(parent, MY_ATOM_ID, NULL);
    subatom != NULL; atom = dsf_iter(parent, MY_ATOM_ID, subatom)) {
    ... work with subatom ...
}

Definition at line 1052 of file dsf.c.

dsf_lookup()

const dsf_atom_t * dsf_lookup	(	const dsf_t *	dsf,
			...
	)

Performs a DSF atom lookup inside of a DSF file. The variadic part of this function must be a list of 32-bit unsigned integers, and MUST be terminated by a zero integer argument. The integers form an path of DSF atom IDs to be searched in the DSF tree structure. If along the way a part of the path sits in a list atom with multiple instances of the same atom ID, this picks the first instance. To search through lists of same-ID atoms, use dsf_lookup_v with a varying index number for the relevant atom path segment.

Returns

The DSF atom at the provided path. If any part of the path was not found, this function returns NULL instead.

See also

dsf_lookup_v

Definition at line 963 of file dsf.c.

dsf_lookup_v()

const dsf_atom_t * dsf_lookup_v	(	const dsf_t *	dsf,
		const dsf_lookup_t *	lookup
	)

Same as dsf_lookup(), but instead of taking a variadic list of atoms to form a path, this takes a flat array of dsf_lookup_t structures.

Parameters

lookup

An array of dsf_lookup_t structures, each identifying a part of the path. The array MUST be terminated by a dsf_lookup_t structure with a zero atom_id field. Use the idx field of the structures to disambiguate which instance of a subatom in a list atom the lookup is meant for.

Returns

The DSF atom at the provided path. If any part of the path was not found, this function returns NULL instead.

See also

dsf_lookup()

Definition at line 1006 of file dsf.c.

dsf_parse()

dsf_t * dsf_parse	(	uint8_t *	buf,
		size_t	bufsz,
		char	reason[DSF_REASON_SZ]
	)

Parses a decompressed DSF file from a memory buffer. You should generally not need to use this function, unless you're streaming DSFs over the net. Use dsf_init() for files store on disk.

Parameters

buf	A buffer containing the decompressed DSF file data.
bufsz	Number of bytes in buf.
reason	A return string, which will be filled with a human-readable failure reason in case parsing of the data fails. If the parse is successful, this buffer is left unaltered.

Returns

A handle to the parsed DSF data, if successful. If there was a failure parsing the data, this returns NULL instead. The reason for the failure is written into the reason argument.

Definition at line 707 of file dsf.c.

dsf_parse_cmds()

bool_t dsf_parse_cmds	(	const dsf_t *	dsf,
		dsf_cmd_cb_t	user_cbs[NUM_DSF_CMDS],
		void *	userinfo,
		char	reason[DSF_REASON_SZ]
	)

Given a DSF file and callback list, iterates through all encoded commands in the DSF file. You can use this to extract the command list in the DSF.

Parameters

dsf	The DSF file to operate on. This file must contain a CMDS atom.
user_cbs	An array of callbacks, with the position in the array denoting what type of command this callback will be called for. You may leave positions in the array set to NULL if you are not interested in receiving a callback for a particular command type.
userinfo	An optional pointer, which will be stored in the dsf_cmd_parser_t structure in the userinfo field. You can extract the userinfo pointer from there.
reason	A failure reason buffer, which will be filled with a human-readable failure description, if a parsing failure occurs.

Returns

B_TRUE if parsing of the command section was successful, or B_FALSE if not.

Definition at line 1081 of file dsf.c.