Add language definition document. Allow execution of codewords without parameter...
[robmyers:surgical_strike.git] / surgical_strike.tex
1 \title{Surgical Strike The Language}
2 \author{Rob Myers}
3
4 \documentclass[12pt]{article}
5
6 \begin{document}
7 \maketitle
8
9 \section{Overview}
10
11 This document defines the syntax of Surgical Strike, a simple (non-Turing-complete) programming language for creating 3D graphics.
12
13 \section{Keywords}
14
15 \subsection{incoming!}
16
17 \texttt{incoming!}
18
19 This keyword must appear once and only once at the start of the program.
20
21 \subsection{camouflage}
22
23 \texttt{camouflage ``filename''}
24
25 Load the specified 3D model file to be inserted when ``deliver'' is called
26
27 In the current implementation, this can be any model format supported by OpenSceneGraph.
28
29 \subsection{deliver}
30
31 \texttt{deliver}
32
33 Add the current payload (the model loaded by ``load'' textured with the bitmap loaded by ``camouflage'') to the theater.
34
35 \subsection{clear}
36
37 \texttt{clear}
38
39 Pop the current transformation matrix from the save stack. 
40
41 \subsection{codeword}
42
43 \texttt{codeword name}
44
45 Start defining a new codeword with the given name.
46
47 This name must be unique within the .strike file.
48
49 It must start with a letter from a-z, and can contain only letters from a-z and numbers from 0-9.
50
51 Codewords cannot contain definitions for other codewords, but may contain calls to them.
52
53 \subsection{load}
54
55 \texttt{payload ``filename''}
56
57 Load the specified 2D bitmap image file to be mapped on to the current model when ``deliver'' is called
58
59 In the current implementation, this can be any 2D bitmap format supported by OpenSceneGraph.
60
61 \subsection{manouver}
62
63 \texttt{manouver radius lambda phi}
64
65 radius is the radius from the current origin, in multiples of the (approximate) bounding sphere of the payload.
66
67 lambda is longitude around the current origin, in degrees.
68
69 phi is latitude around the current origin, in degrees.
70
71 \subsection{mark}
72
73 \texttt{mark}
74
75 Push the current transformation matrix onto the save stack. 
76
77 \subsection{roll}
78
79 \texttt{roll x y z}
80
81 x is added to rotation around the x axis.
82
83 y is added to rotation around the y axis.
84
85 z is added to rotation around the z axis.
86
87 \subsection{scale}
88
89 \texttt{scale x y z}
90
91 x is added to the scale of units along the x axis.
92
93 y is added to the scale of units along the y axis.
94
95 z is added to the scale of units along the z axis.
96
97 \subsection{set}
98
99 \texttt{set}
100
101 Finish defining the codeword that began being defined with ``codeword''.
102
103 \section{Defining Codewords}
104
105 Codeword definitions have the following form:
106
107 \texttt{
108 codeword klin
109   manouver 0 0 45
110   deliver
111 set
112 }
113
114 This creates a codeword named ``klin'' that moves 45 degrees and then adds an instance of the current model to the theater.
115
116 \section{Executing Codewords}
117
118 Codeword invocations must have one of the following forms:
119
120 \texttt{
121 klin
122 }
123
124 This will execute the previously defined codeword ``klin''.
125
126 \texttt{
127 klin 12
128 }
129
130 This will execute the previously defined codeword ``klin'' 12 times.
131
132 \end{document}