--- /dev/null
+A Few Notes on the New Object Processor Assembler
+-------------------------------------------------
+
+Q: What is it?
+
+A: An assembler to generate object lists for the Atari Jaguar's Object
+ processor.
+
+
+Q: Why is it here?
+
+A: To really utilize the OP properly, it needs an assembler. Otherwise, what
+ happens is you end up writing an assembler in your code to assemble the OP
+ list, and that's a real drag--something that *should* be handled by a proper
+ assembler.
+
+
+Q: How do I use it?
+
+A: The OP assembler works similarly to the RISC assembler; to enter the OP
+ assembler, you put the .objproc directive in your code (N.B.: like the RISC
+ assembler, it only works in a TEXT or DATA section). From there, you build
+ the OP list how you want it and go from there. A few caveats: you will want
+ to put a .org directive at the top of your list, and labels that you want to
+ be able to address in 68xxx code (for moving from a data section to an
+ address where it will be executed by the OP, for example) should be created
+ in .68xxx mode.
+
+
+Q: What are the opcodes?
+
+A: They are bitmap, scbitmap, gpuobj, branch, stop, nop, and jump. nop and jump
+ are psuedo-ops, they are there as a convenience to the coder.
+
+
+Q: What are the proper forms for these opcodes?
+
+A: They are as follows:
+
+ bitmap <data addr>, <xloc>, <yloc>, <dwidth>, <iwidth>, <iheight>, <bpp>,
+ <pallete idx>, <flags>, <firstpix>, <pitch>
+ scbitmap <data addr>, <xloc>, <yloc>, <dwidth>, <iwidth>, <iheight>,
+ <xscale>, <yscale>, <remainder>, <bpp>, <pallete idx>,
+ <flags>, <firstpix>, <pitch>
+ gpuobj <line #>, <userdata> (bits 14-63 of this object)
+ branch VC <condition (<, =, >)> <line #>, <link addr>
+ branch OPFLAG, <link addr>
+ branch SECHALF, <link addr>
+ stop
+ nop
+ jump <link addr>
+
+ Note that the <flags> field in bitmap and scbitmap objects consist of the
+ following: REFLECT, RMW, TRANS, RELEASE. They can be in any order (and
+ should be separated by whitespace *only*), and you can only put a maximum of
+ four of them in. Further note that with bitmap and scbitmap objects, all the
+ parameters after <data addr> are optional--if they are omitted, they will
+ use defaults (mostly 0, but 1 is the default for pitch). Also, in the
+ scbitmap object, the <xscale>, <yscale>, and <remainder> fields can be
+ floating point constants/expressions. <data addr> can refer to any address
+ defined (even external!) and the linker (rln v1.6.0 or greater) will
+ properly fix up the address.
+
+
+Q: What do they do?
+
+A: Pretty much what you expect. It's beyond the scope of this little note to
+ explain the Jaguar's Object Processor and how it operates, so you'll have to
+ seek explanations for how they work elsewhere.
+
+
+Q: Why do I want to put a .org directive at the top of my list?
+
+A: You want to put a .org directive at the top of your list because otherwise
+ the assembler will not know where in memory the object list is supposed
+ go--then when you move it to its destination, the object link addresses will
+ all be wrong and it won't work.
+
+
+Q: Why would I copy my object list to another memory location?
+
+A: Simple: because the OP destroys the list as it uses it to render the screen.
+ If you don't keep a fresh copy stashed away somewhere to refresh it before
+ the next frame is rendered, what you see on the screen will not be what you
+ expect, as the OP has scribbled all over it!
+
+
+Q: Does the assembler do anything behind my back?
+
+A: Yes, it will emit NOPs to ensure that bitmaps and scbitmaps are on proper
+ memory boundaries, and fixup link addresses as necessary. This is needed
+ because of a quirk in how the OP works (it ORs constants on the address
+ lines to get the phrases it needs and if they are not zeroes, it will fail
+ in bizarre ways).
+
+
+Q: Why can't I define the link addresses for all the objects?
+
+A: You really, *really* don't want to do this. Trust me on this one.
+
+
+Q: How about an example of an object list?
+
+A: Here you go:
+
+ objList = $10000
+ bRam = $20000
+;
+ .68000
+objects: ; This is the label you will use to address this in 68K code
+ .objproc ; Engage the OP assembler
+ .org objList ; Tell the OP assembler where the list will execute
+;
+ branch VC < 69, .stahp ; Branch to the STOP object if VC < 69
+ branch VC > 241, .stahp ; Branch to the STOP object if VC > 241
+ bitmap bRAM, 22, 70, 24, 24, 22, 4
+ bitmap bRAM, 20+96+96, 70, 24, 24, 22, 4, 0, REFLECT
+ scbitmap tms, 20, 70, 1, 1, 8, 3.0, 3.0, 2.9999, 0, 0, TRANS
+ scbitmap tmsShadow, 23, 73, 1, 1, 8, 3.0, 3.0, 2.9999, 0, 3, TRANS
+ bitmap sbRelBM, 30, 108, 3, 3, 8, 0, 1, TRANS
+ bitmap txt1BM, 46, 132, 3, 3, 8, 0, 2, TRANS
+ bitmap txt2BM, 46, 148, 3, 3, 8, 0, 2, TRANS
+ bitmap txt3BM, 22, 164, 3, 3, 8, 0, 2, TRANS
+ jump .haha
+.stahp:
+ stop
+.haha:
+ jump .stahp
+