2 \brief Intermediate Representation (IR) between Directory Structure and Engine Grammar
3 \details The IR serves as a storage structure that is populated during the
4 parsing of the input directory structure. After parsing is complete,
5 the IR will be condensed (removed of excess allocated space) and then
6 output as the Engine Grammar. In this file we describe the semantic actions
7 that are called at each step, and the memory buffers that they populate.
8 See parser.y for the description on how the input grammar is constructed,
9 and where/when semantic actions are called.
10 TODO: or just write it here.
11 \author Jordan Lavatai
13 ----------------------------------------------------------------------------*/
17 //#include <apc/mem.h>TODO:
23 #define MAX_MODELS 256
25 #define MAX_CLASS_DEPTH 256
26 #define MAX_CLASSES 256
27 #define MAX_FRAMES 256
28 /* All bufs are of pointers to their respective structs. When a buf is full */
29 /* (number of data structs pointers >= max number of data struct pointers), */
30 /* we need to allocate a more pointers for that buf. Allocate these */
31 /* pointers a page at a time (1024 = Page bytes (4096)/bytes per pointer(4)) */
32 /* TODO: Account for different page sizes in different system */
33 #define PTRS_IN_PAGE 1024
35 /* General: All information from the directory structure is stored in */
36 /* five buffers that comprise the IR: cdat_buf, odat_buf, vdat_buf, ref_buf */
37 /* and link_buf. Each buf corresponds to the data structure that it stores. */
38 /* The storage techique for all bufs (except cdat) is the same. Each bufs member first */
39 /* populates its struct and then allocates the space for the next member */
40 /* and increments the buf index. This means that we have to allocate the */
41 /* very first member of each buf at ir_init(), so that we don't segfault */
42 /* as the first member attempts to access memory that its previous member */
43 /* didn't allocate (because it doesnt exist). We access the buf members */
44 /* through standard array indexing but conceal the tediousness of array */
45 /* indexing with macros. E.g. without macros, acessing an elements name */
46 /* member would look like (split up to not go over line char limit): */
47 /* (*cdat_stackp)->set_list[(*cdat_stackp)->num_sets] */
48 /* .ele_list[(*cdat_stackp)->set_list[(*cdat_stackp->num_sets)].num_ele].name */
50 /* For cdats in cdat_buf, we allocate the memory for a cdat once a cdat
51 is recognized in the grammar. Cdat_buf is different from the other bufs
52 because cdats have a root cdat that all cdats are a subclass of. This root
53 cdat can have a set_list like other cdats. */
58 /* Elements: Ele stands for element and has two representations in the IR. */
59 /* In the cdat_buf eles store their name, cdat_idx (their classes index in */
60 /* the cdat_buf) and the ref_id (refer to ref ). In the odat_buf, eles store */
61 /* their object data (odat). At output time, the ref_id is dereferenced to */
62 /* determine the elements odat which is the data that the engine expects */
63 /* from an element. */
71 /* Sets: The set is similar to the ele, but it contains a list of its */
72 /* elements. The set is populated at parse time AFTER the elements are */
73 /* populated, due to the nature of bottom up parsing. */
80 struct ele ele_list
[MAX_ELES
];
83 /* Cdats: A cdat is a class data structure. Cdats serve as the central */
84 /* data types of the IR. At output, the cdat_buf is iterated through and */
85 /* each is written to the output file. For each cdat, sets and element */
86 /* ref_ids must be dereferenced to determine the odat information. Cdats */
87 /* contain pointers to their subclasses so that the relationship between */
88 /* classes can be determined, but the subclasses are not represented inside */
89 /* of the cdat itself but rather in the subsequent cdats in cdat_buf. We */
90 /* can determine the number of subclasses (the last index into cdat_buf */
91 /* that represents a subclass of some arbitrary cdat) each cdat has by */
92 /* incrementing num_classes during parse time. */
93 /* TODO: Should classes point to their parent class? */
100 struct cdat
* class_list
[MAX_CLASSES
];
101 struct set set_list
[MAX_SETS
];
104 /* There are an unknown amount of cdats at compile time, so we maintain */
105 /* a cdat_buf of cdat pointers that can be expanded as needed. */
106 struct cdat
* cdat_buf
[PTRS_IN_PAGE
];
108 int curr_max_cdats
= PTRS_IN_PAGE
;
110 /* The cdat_stack is a stack pointers to cdat pointers, the top of which is
111 the cdat that is currently being parsed. Whenever a new cdat is recognized
112 by the grammar (CLOPEN), a cdat is pushed onto the cdat_stack, and we refer
113 to this cdat through the macro CURR_CDAT. By keeping a cdat_stack, we have
114 access to the current cdat so that the elements and sets can populate themselves
115 in the cdat accordingly. */
117 struct cdat
* cdat_stack
[PTRS_IN_PAGE
];
118 struct cdat
** cdat_stackp
;
120 /* Refs: Each set/ele has a reference to its object data (odat) through a ref_id.
121 Ref_ids are unsigned 64 byte integers that map to the hex values RGBA. During
122 the construction of the directory structure, users can choose a RGBA value for
123 each object that any other object can refer to via links (see link). If a user
124 does not choose an RGBA value, then the object is given one from the system space.
125 We maintain a doubly linked list of refs in the ref_buf at parse time so that
126 links can be resolved after the parsing of the directory structure is complete.
127 For every 16th ref, we create a post so that we can reduce on the search time for
135 uint64_t ref_id
; //0xFFFFFF->digit
138 /* Like the cdat_buf, ref_buf stores pointers to refs and can
140 struct ref
* ref_buf
[PTRS_IN_PAGE
];
142 int curr_max_refs
= PTRS_IN_PAGE
;
143 uint64_t ss_ref_id
= 0x00FFFFFF; /* system space for ref_ids */
146 /* posts for ref_buf */
147 struct ref posts
[MAX_POSTS
];
150 /* Links: At parse time, a set/ele can include a link in their
151 grammar representation instead of the actual data and this signifies
152 to the APC that that set/ele wishes to use the data of another
153 set/ele, either its video data (vdat) or object data (odat). The link
154 itself contains the type of link it is, the ref_id OR name, and
155 which set/ele created the link. During parse time, links can be made
156 to o/vdats that have yet to be parsed. In order to accomodate for this,
157 we resolve all links AFTER parse time by iterating through the link_buf,
158 finding the ref_id that was stored for some object (if the ref_id exists),
159 and creating a relative pointer from the original object to the data that
162 /* Svlinks stand for short vlink, which is a link to a vdat
163 TODO: diff btwn vlink*/
169 /* A vlink is what it sounds like, a link to a vdat
176 /* Olinks are links to odats */
184 struct svlink svlink
;
188 int type
; //1 = olink, 2 = vlink, 3 = svlink
194 /* link_buf contains all the links that
195 we encountered during parse time that need
196 to be resolved to an offset at output time.
197 This does not include quad refs, because
198 those are already known to need to be resolved */
199 struct link
* link_buf
[PTRS_IN_PAGE
];
201 int curr_max_links
= PTRS_IN_PAGE
;
204 /* Odats: Odats consist of the object data necessary for
205 each object. Odats are sometimes referred to as archetypes
206 at compile-time, in order to distinguish the difference from
207 a runtime object and a compile-time object.
208 TODO: Need more info about objects at runtime, to described
209 the reasoning behind odat structure at compile-time*/
211 /* Each set has a quad_list or a list of quads. The quad_list
215 uint64_t ref_id
; //rgba
228 struct ref
* refp
; /* pointer to it's ref on ref_list */
230 struct quad quad_list
[MAX_QUADS
];
233 /* Populated and allocated same way as other bufs */
234 struct odat
* odat_buf
[PTRS_IN_PAGE
];
235 int curr_max_odats
= PTRS_IN_PAGE
;
238 /* A framesheet is a grouping of animation frames in
239 a single direction (N,W,S,E) */
244 void* frames
[MAX_FRAMES
];
247 /* A model is a collection of framesheets for every
248 direction (N,W,S,E,NW,NE,SW,SE)*/
249 /* NAMED spritesheet */
252 struct framesheet spritesheet
[8]; //one for each
255 /* Vdat: Vdats are the video data of each object. They can not be
256 created as a stand alone object (because they consist solely
257 of animation information and not the skeleton on which the
258 animation manipulates). Vdats have a list of models for every
259 animation that the vdats odat can do for that vdat*/
261 struct odat
* creator
; //pointer to odat that made this vdat
263 struct model model_list
[MAX_MODELS
];
267 struct vdat
* vdat_buf
[PTRS_IN_PAGE
];
268 int curr_max_vdats
= PTRS_IN_PAGE
;
271 /* The initalization function of the IR. Mallocs the
272 first c/v/odat and the first links and refs and
273 inits the cdat_stack */
277 /* mallocs memory for a new cdat. If the cdat_buf
278 is full, mallocs another 1024 cdat pointers. */
282 /* Called after the cdat open operator has been recognized in grammar. Allocates
283 the space for a cdat on the cdat_buf, pushes that pointer onto
288 /* Called after a cdat end operator has been recognized in grammar. Sets
289 top stack cdat ** to null and decrements stack pointer */
293 /* Called after an odat has been populated. Allocates memory for
298 /* Called after an vdat has been populated. Allocates memory for
309 /* Called in the reduction of a set. While both odats (eles and sets)
310 have identical label terminals, we are unable to give a single grammatical rule
311 for both due to how we allocate odats in the odat buf. Due to the
312 nature of bottom up parsing, all the elements will be inserted into the
313 odat_buf first, and then the set that contains these element is inserted. Since
314 the sets label comes before the element list in the grammar, we would be giving an element
315 a set label in its respective odat, which would then be replaced by the
316 elements label. Instead, we store the label in the sets representation inside
317 CURR_CDAT and after we are done parsing the element_list and know that the CURR_ODAT
318 is the set, we populate the sets label members in CURR_ODAT with the values we stored
319 previously in CURR_CDAT. */
321 insert_set_label(char*, uint64_t);
323 /* Populate the sets representation in CURR_CDAT with a ref_id and insert a link
324 into the link_buf that will resolve the ref_id to an actual odat after parse time. */
326 insert_set_olink(uint64_t);
328 /* Put the vlink in the link_buf to be processed after parsetime */
330 insert_set_vlink(uint64_t, char*);
332 /* Put svlink in the link_buf to be processed after parsetime */
334 insert_set_svlink(uint64_t);
336 /* Called for every set reduction except for sets with olinks. Populates the
337 set data structures in the CDAT and in the ODAT. Uses the name and ref_id
338 from insert_set_label. Also inserts a ref into the ref_buf with the CURR_ODAT
339 pointer so that we can also resolve the odat from its ref_id. */
343 /* Insertion of eles is practically equivalent to how sets are inserted because both
344 share the same data type (ODAT). Like sets, eles have links, labels
345 and odats. Eles have the added notion of a parent set, and so must be inserted
346 into said parent set, but this is the only place they truly differ from sets. */
349 insert_ele_label(char*, uint64_t);
352 insert_ele_olink(uint64_t);
355 insert_ele_vlink(uint64_t, char*);
358 insert_ele_svlink(uint64_t);
363 /* Created as a seperate function, instead of setting the ODATS vdat_id and
364 calling inc_vdat() inside of insert_set(), to account for the set reduction
365 where a vdat is not created (o/v/svlinks). Because insert_set/ele is always
366 called before insert_vdat, and thus increments the CURR_ODAT to be the next
367 ODAT to be populated, insert_vdat() targets the last ODAT that was populated,
372 /* Inserts the hitbox into the CURR_ODAT */
376 /* Inserts the root into the CURR_ODAT */
378 insert_root(int, int, int);
380 /* Inserts a quad into the CURR_ODAT */
382 insert_quad(int, int, int, uint64_t);
388 insert_framesheet(char, char*, uint64_t, int, int, int);
391 insert_frame_pointer(char, void*);