Implement ^^FILESIZE unary operator that returns the file size of a given file. Minor...
[rmac] / docs / note-on-the-op-assembler.txt
1 A Few Notes on the New Object Processor Assembler
2 -------------------------------------------------
3
4 Q: What is it?
5
6 A: An assembler to generate object lists for the Atari Jaguar's Object
7    processor.
8
9
10 Q: Why is it here?
11
12 A: To really utilize the OP properly, it needs an assembler. Otherwise, what
13    happens is you end up writing an assembler in your code to assemble the OP
14    list, and that's a real drag--something that *should* be handled by a proper
15    assembler.
16
17
18 Q: How do I use it?
19
20 A: The OP assembler works similarly to the RISC assembler; to enter the OP
21    assembler, you put the .objproc directive in your code (N.B.: like the RISC
22    assembler, it only works in a TEXT or DATA section). From there, you build
23    the OP list how you want it and go from there. A few caveats: you will want
24    to put a .org directive at the top of your list, and labels that you want to
25    be able to address in 68xxx code (for moving from a data section to an
26    address where it will be executed by the OP, for example) should be created
27    in .68xxx mode.
28
29
30 Q: What are the opcodes?
31
32 A: They are bitmap, scbitmap, gpuobj, branch, stop, nop, and jump. nop and jump
33    are psuedo-ops, they are there as a convenience to the coder.
34
35
36 Q: What are the proper forms for these opcodes?
37
38 A: They are as follows:
39
40    bitmap <data addr>, <xloc>, <yloc>, <dwidth>, <iwidth>, <iheight>, <bpp>,
41           <pallete idx>, <flags>, <firstpix>, <pitch>
42    scbitmap <data addr>, <xloc>, <yloc>, <dwidth>, <iwidth>, <iheight>,
43             <xscale>, <yscale>, <remainder>, <bpp>, <pallete idx>,
44             <flags>, <firstpix>, <pitch>
45    gpuobj <line #>, <userdata> (bits 14-63 of this object)
46    branch VC <condition (<, =, >)> <line #>, <link addr>
47    branch OPFLAG, <link addr>
48    branch SECHALF, <link addr>
49    stop
50    nop
51    jump <link addr>
52
53    Note that the <flags> field in bitmap and scbitmap objects consist of the
54    following: REFLECT, RMW, TRANS, RELEASE. They can be in any order (and
55    should be separated by whitespace *only*), and you can only put a maximum of
56    four of them in. Further note that with bitmap and scbitmap objects, all the
57    parameters after <data addr> are optional--if they are omitted, they will
58    use defaults (mostly 0, but 1 is the default for pitch). Also, in the
59    scbitmap object, the <xscale>, <yscale>, and <remainder> fields can be
60    floating point constants/expressions. <data addr> can refer to any address
61    defined (even external!) and the linker (rln v1.6.0 or greater) will
62    properly fix up the address.
63
64
65 Q: What do they do?
66
67 A: Pretty much what you expect. It's beyond the scope of this little note to
68    explain the Jaguar's Object Processor and how it operates, so you'll have to
69    seek explanations for how they work elsewhere.
70
71
72 Q: Why do I want to put a .org directive at the top of my list?
73
74 A: You want to put a .org directive at the top of your list because otherwise
75    the assembler will not know where in memory the object list is supposed
76    go--then when you move it to its destination, the object link addresses will
77    all be wrong and it won't work.
78
79
80 Q: Why would I copy my object list to another memory location?
81
82 A: Simple: because the OP destroys the list as it uses it to render the screen.
83    If you don't keep a fresh copy stashed away somewhere to refresh it before
84    the next frame is rendered, what you see on the screen will not be what you
85    expect, as the OP has scribbled all over it!
86
87
88 Q: Does the assembler do anything behind my back?
89
90 A: Yes, it will emit NOPs to ensure that bitmaps and scbitmaps are on proper
91    memory boundaries, and fixup link addresses as necessary. This is needed
92    because of a quirk in how the OP works (it ORs constants on the address
93    lines to get the phrases it needs and if they are not zeroes, it will fail
94    in bizarre ways). It will also set all <ypos> constants on the correct
95    half-line (as that's how the OP views them).
96
97
98 Q: Why can't I define the link addresses for all the objects?
99
100 A: You really, *really* don't want to do this. Trust me on this one.
101
102
103 Q: How about an example of an object list?
104
105 A: Here you go:
106
107                 objList = $10000
108                 bRam = $20000
109 ;
110                 .68000
111 objects:                        ; This is the label you will use to address this in 68K code
112                 .objproc        ; Engage the OP assembler
113                 .org    objList ; Tell the OP assembler where the list will execute
114 ;
115                 branch          VC < 69, .stahp         ; Branch to the STOP object if VC < 69
116                 branch          VC > 241, .stahp        ; Branch to the STOP object if VC > 241
117                 bitmap          bRAM, 22, 70, 24, 24, 22, 4
118                 bitmap          bRAM, 20+96+96, 70, 24, 24, 22, 4, 0, REFLECT
119                 scbitmap        tms, 20, 70, 1, 1, 8, 3.0, 3.0, 2.9999, 0, 0, TRANS
120                 scbitmap        tmsShadow, 23, 73, 1, 1, 8, 3.0, 3.0, 2.9999, 0, 3, TRANS
121                 bitmap          sbRelBM, 30, 108, 3, 3, 8, 0, 1, TRANS
122                 bitmap          txt1BM, 46, 132, 3, 3, 8, 0, 2, TRANS
123                 bitmap          txt2BM, 46, 148, 3, 3, 8, 0, 2, TRANS
124                 bitmap          txt3BM, 22, 164, 3, 3, 8, 0, 2, TRANS
125                 jump            .haha
126 .stahp:
127                 stop
128 .haha:
129                 jump            .stahp
130