api update
[henge/apc.git] / src / ir.h
1 /*!@file
3 \brief Intermediate Representation (IR) between Directory Structure and Engine
4 Input
6 \details The IR serves as a storage structure that is populated during the
7 parsing of the input directory structure. After parsing is complete,
8 the IR will be condensed (removed of excess allocated space) and then
9 output as the input for the engine. In this file we describe the
10 semantic actions that are called at each step, and the memory buffers
11 that they populate. See parser.y for the description on how the input
12 grammar is constructed, and where/when semantic actions are called.
14 All input values are duplicated internally and their memory may be
15 freed.
17 \author Jordan Lavatai
18 \date Aug 2016
19 ----------------------------------------------------------------------------*/
20 #ifndef _IR_H_
21 #define _IR_H_
22 #include <unitypes.h>
23 #include "apc.h"
25 struct ir_frameinfo_t
26 { int facing, w, h; };
27 typedef union ir_setdata_t* ir_setdata;
28 typedef struct ir_frameinfo_t* ir_frameinfo;
29 typedef struct ir_set_t* ir_set;
30 typedef struct ir_class_t* ir_class;
31 typedef struct ir_setld_t* ir_setld;
32 typedef struct ir_classld_t* ir_classld;
33 /* Classes and Sets
34 Classes are rooted at a special root class, representing the current working
35 directory at scan-time, named ".". The root class can always be identified
36 with ir_class_root, and children may be added to it. The add series of
37 functions will return a reference to the newly created object, which may also
38 be used the root for further add functions.
40 E.G.
41 ir_class x = ir_class_root();
42 x = ir_class_addchild(x, "mychild");
43 x = ir_class_addchild(x, "child of mychild");
45 Sets, like classes, must be rooted. Unlike classes, sets may be rooted on
46 other sets, in addition to classes. ir_class_addset will return a set rooted
47 on the class specified, while ir_set_addchild will return a set rooted on the
48 specified set.
49 */
50 ir_class ir_class_root(void);
51 ir_class ir_class_addchild(ir_class,const uint8_t*);
52 uint8_t* ir_class_name(ir_class);
53 ir_set ir_class_addset(ir_class,const uint8_t*);
54 ir_set ir_set_addchild(ir_set,const uint8_t*);
55 uint8_t* ir_set_name(ir_set);
56 /* Output */
57 ir_class ir_class_nextsib(ir_class);
58 ir_class ir_class_nextchild(ir_class);
59 long ir_class_fpos(ir_class);
60 void ir_class_assign_fpos(ir_class,long);
61 ir_set ir_set_from_ref(uint32_t);
62 ir_set ir_set_nextsib(ir_set);
63 ir_set ir_set_nextchild(ir_set);
64 long ir_set_fpos(ir_set);
65 void ir_set_assign_fpos(ir_set,long);
66 /* Set Data
67 Each set can contain up to FACING_MAX each of framesheets and mapsheets, one
68 sheet for each facing, per label. Each set can contain any number of audio
69 objects, supplied by label. Repeat assignment of conflicting data (e.g. two
70 SFACE framesheets assigned to the same set and label, or two audio objects
71 with the same label) causes an internal error.
72 Each set may also contain any number of link objects, which will be linked in
73 the order that they are encountered. At link time, repeated assignments of
74 conflicting data cause data to be silently overwritten for those sets. This
75 is an intentional side-effect of the linker.
76 Each setdata may have a path associated with it. If the data depends on the
77 data of an associated file at that path and no path is provided, the data
78 will be entered null.
79 */
80 typedef ir_setdata ir_framebox;
81 typedef ir_setdata ir_audio;
82 typedef ir_setdata ir_link;
83 typedef ir_setdata ir_framedata;
84 enum ltype { OLINK, MLINK, VLINK, ALINK };
85 void ir_set_assign_data(ir_set,ir_setdata);
86 void ir_set_assign_ref(ir_set,uint32_t);
87 void ir_data_assign_path(ir_setdata,const uint8_t*);
88 ir_setdata ir_framesheet(const uint8_t*, apc_facing, int,int);
89 ir_setdata ir_mapsheet(const uint8_t*, apc_facing, int,int);
90 ir_setdata ir_audio(const uint8_t*);
91 ir_setdata ir_link(enum ltype,ir_setld,const uint8_t*);
92 /* Output */
93 ir_framebox ir_set_framebox(ir_set);
94 ir_audio ir_set_audio(ir_set);
95 ir_link ir_set_link(ir_set);
96 ir_setdata ir_setdata_nextsib(ir_setdata);
97 uint8_t* ir_setdata_name(ir_setdata);
98 uint8_t* ir_setdata_filename(ir_setdata);
99 long ir_setdata_fpos(void);
100 void ir_setdata_assign_fpos(ir_setdata,long);
101 ir_framedata ir_framebox_framesheet(ir_framebox,apc_facing);
102 ir_framedata ir_framebox_mapsheet(ir_framebox,apc_facing);
103 ir_frameinfo ir_framedata_frameinfo(ir_framedata);
104 /* Reference Linking Data
105 Create linking data to sets or classes that will be resolved at a later
106 stage. Class references can be created from an ir_class object, if
107 available, or from the root class. Set references can be created from a
108 64-bit integer ID, or from a class linking data and a child name. Once
109 created, both Class and Set link data can traverse children, specified by
110 name, which will be resolved at the linking stage as well.
111 */
112 ir_classld ir_classld_from_class(ir_class);
113 ir_classld ir_classld_from_root(void);
114 ir_classld ir_classld_addchild(ir_classld,const uint8_t*);
115 ir_setld ir_setld_from_ref(uint32_t);
116 ir_setld ir_setld_from_classld(ir_classld,const uint8_t*);
117 ir_setld ir_setld_addchild(ir_setld,const uint8_t*);
118 /* Output */
119 enum ltype ir_setld_type(ir_setld);
120 uint32_t ir_setld_ref(ir_setld);
121 #endif //_IR_H_