Shamusworld >> Repos - rmac/blob - 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).
  95
  96
  97 Q: Why can't I define the link addresses for all the objects?
  98
  99 A: You really, *really* don't want to do this. Trust me on this one.
 100
 101
 102 Q: How about an example of an object list?
 103
 104 A: Here you go:
 105
 106                 objList = $10000
 107                 bRam = $20000
 108 ;
 109                 .68000
 110 objects:                        ; This is the label you will use to address this in 68K code
 111                 .objproc        ; Engage the OP assembler
 112                 .org    objList ; Tell the OP assembler where the list will execute
 113 ;
 114                 branch          VC < 69, .stahp         ; Branch to the STOP object if VC < 69
 115                 branch          VC > 241, .stahp        ; Branch to the STOP object if VC > 241
 116                 bitmap          bRAM, 22, 70, 24, 24, 22, 4
 117                 bitmap          bRAM, 20+96+96, 70, 24, 24, 22, 4, 0, REFLECT
 118                 scbitmap        tms, 20, 70, 1, 1, 8, 3.0, 3.0, 2.9999, 0, 0, TRANS
 119                 scbitmap        tmsShadow, 23, 73, 1, 1, 8, 3.0, 3.0, 2.9999, 0, 3, TRANS
 120                 bitmap          sbRelBM, 30, 108, 3, 3, 8, 0, 1, TRANS
 121                 bitmap          txt1BM, 46, 132, 3, 3, 8, 0, 2, TRANS
 122                 bitmap          txt2BM, 46, 148, 3, 3, 8, 0, 2, TRANS
 123                 bitmap          txt3BM, 22, 164, 3, 3, 8, 0, 2, TRANS
 124                 jump            .haha
 125 .stahp:
 126                 stop
 127 .haha:
 128                 jump            .stahp
 129