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). It will also set all <ypos> constants on the correct
   half-line (as that's how the OP views them).


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

