From 054d902d3a6e11245ece94207594219b0107f87c Mon Sep 17 00:00:00 2001 From: Bill Currie Date: Sun, 9 Dec 2012 19:43:12 +0900 Subject: [PATCH] Document alias defs. The diagram showing the basics of how alias defs work is in a spearate file because it created to much clutter in the header file. --- doc/quakeforge.dox.conf.in | 2 +- tools/qfcc/doc/Makefile.am | 3 ++- tools/qfcc/doc/dot/vector-alias.dot | 25 +++++++++++++++++++++++++ tools/qfcc/include/def.h | 22 +++++++++++++++++++++- 4 files changed, 49 insertions(+), 3 deletions(-) create mode 100644 tools/qfcc/doc/dot/vector-alias.dot diff --git a/doc/quakeforge.dox.conf.in b/doc/quakeforge.dox.conf.in index db41ae4a2..0157cff40 100644 --- a/doc/quakeforge.dox.conf.in +++ b/doc/quakeforge.dox.conf.in @@ -1770,7 +1770,7 @@ DOT_PATH = # contain dot files that are included in the documentation (see the # \dotfile command). -DOTFILE_DIRS = +DOTFILE_DIRS = @TOPSRC@/tools/qfcc/doc/dot # The MSCFILE_DIRS tag can be used to specify one or more directories that # contain msc files that are included in the documentation (see the diff --git a/tools/qfcc/doc/Makefile.am b/tools/qfcc/doc/Makefile.am index a0a60809c..8d0026abb 100644 --- a/tools/qfcc/doc/Makefile.am +++ b/tools/qfcc/doc/Makefile.am @@ -2,4 +2,5 @@ AUTOMAKE_OPTIONS= foreign SUBDIRS= man -EXTRA_DIST= expressions.txt +EXTRA_DIST= expressions.txt \ + dot/vector-alias.dot diff --git a/tools/qfcc/doc/dot/vector-alias.dot b/tools/qfcc/doc/dot/vector-alias.dot new file mode 100644 index 000000000..58e0fb117 --- /dev/null +++ b/tools/qfcc/doc/dot/vector-alias.dot @@ -0,0 +1,25 @@ +digraph vector_alias { + rankdir=LR; + subgraph types { + rank = same; + vector [fontsize=10,label="type\nvector"]; + float [fontsize=10,label="type\nfloat"]; + } + subgraph alias { + vec [fontsize=10,shape=record,label="vec|next|type|alias|alias_defs|offset ?|..."]; + vec_x [fontsize=10,shape=record,label="vec.x|next|type|alias|alias_defs|offset 0|..."]; + vec_y [fontsize=10,shape=record,label="vec.y|next|type|alias|alias_defs|offset 1|..."]; + vec_z [fontsize=10,shape=record,label= "vec.z|next|type|alias|alias_defs|offset 2|..."]; + } + vector -> float [style=invis]; + vec:t -> vector [weight=2]; + vec_x:t -> float [weight=2]; + vec_y:t -> float [weight=2]; + vec_z:t -> float [weight=2]; + vec:d -> vec_z:v [weight=5]; + vec_z:n -> vec_y:v [weight=15]; + vec_y:n -> vec_x:v [weight=15]; + vec:v -> vec_z:a [dir=back,weight=4]; + vec:v -> vec_y:a [dir=back,weight=4]; + vec:v -> vec_x:a [dir=back,weight=4]; +} diff --git a/tools/qfcc/include/def.h b/tools/qfcc/include/def.h index a8005ba11..77a839887 100644 --- a/tools/qfcc/include/def.h +++ b/tools/qfcc/include/def.h @@ -54,15 +54,35 @@ struct expr_s; */ typedef struct def_s { struct def_s *next; ///< general purpose linking - struct def_s *temp_next; ///< linked list of "free" temp defs + struct type_s *type; ///< QC type of this def const char *name; ///< the def's name struct defspace_s *space; ///< defspace to which this def belongs int offset; ///< address of this def in its defspace + /** \name Def aliasing. + Aliasing a def provides a different view of the def providing access + via a different type, or access to members of structs, unions and + arrays. + + Alias defs are very simple: they store only the type and relative + offset off the def they alias. All other information is held in the + def they alias, including relocation records. However, they do keep + track of the source file and line that first created the alias. + + The relations between a def an any of its aliases are maintained by + a linked list headed by def_t::alias_defs and connected by + def_t::next. def_t::alias is used to find the main def via one if its + aliases. The order of the aliases in the list is arbitrary: it is the + reverse of the order in which they were created. + + \dotfile vector-alias.dot "Accessing a vector via its components." + */ + //@{ struct def_s *alias_defs; ///< defs that alias this def struct def_s *alias; ///< real def which this def aliases + //@} struct reloc_s *relocs; ///< for relocations struct expr_s *initializer;///< initialer expression struct daglabel_s *daglabel;///< daglabel for this def