chiark - git - mdw - ssr/blob - StraySrc/Libraries/Sapphire/Modules/Docs/Sprinkle

   1
   2      /####\  ######\  ######\   ####   ###\   ##  ##  /#/  ##      ######
   3      ##/     ##   )#  ##   )#    ##    ##\#\  ##  ## /#/   ##      ##
   4      \####\  ######/  ######/    ##    ## \#\ ##  ##<#<    ##      #####
   5         \##  ##       ##  \#\    ##    ##  \#\##  ## \#\   ##      ##
   6      \####/  ##       ##   \#\  ####   ##   \###  ##  \#\  ######  ######
   7
   8                       ©   1 9 9 5   S t r a y l i g h t
   9
  10 _____________________________________________________________________________
  11
  12
  13                                 About Sprinkle
  14
  15         Sprite areas are just big blocks of memory with lots of sprites in,
  16         and this is all well and good.  Until you want to add some more
  17         without making the whole area move.
  18
  19         The problem becomes particularly awkward when you start writing
  20         extendable applications (e.g., using Straylight's Dynamic Linking
  21         System) and you want to allow each extension DLL to have its own
  22         sprites file which are joined to the main one.
  23
  24         There are traditionally three possible solutions to the problem:
  25
  26          1. Forget it.  Force the sprites to be in the main application's
  27             sprites file.  Extensions can't have their own sprites, or
  28             they have to merge them with the main file at installation
  29             time
  30
  31          2. Make the block bigger and then merge the files.  This will cause
  32             your heap to fragment, and the sprite area to move, so you
  33             mustn't have any windows created which use the sprite area.
  34             Alternatively, you could put the sprite area at the bottom of a
  35             shifting heap, and extend it there, so that the area itself
  36             doesn't move.  This prevents you from having a non-shifting heap
  37             there, though.  I think this is the approach which ArtWorks uses.
  38
  39          3. Make each extension have its own sprite area, which it has to
  40             manage itself.  This makes it awkward to use shared sprites
  41             from the kernel's sprite file, and can be wasteful of space.
  42
  43         Sprinkle is `Option 4 -- make the Operating System nicer.'
  44
  45 _____________________________________________________________________________
  46
  47
  48                               The basic concept
  49
  50         The whole problem outlined above is caused by the sprite areas being
  51         in big contiguous blocks.  It would all go away if you could instead
  52         put sprites into linked lists, which you could extend at run-time
  53         without any of the heartache normally caused by this.  Sprinkle is
  54         a small patch which allows you to link sprite areas together, so
  55         you can access a sprite in any of the linked areas just by pointing
  56         at the first one.
  57
  58 _____________________________________________________________________________
  59
  60
  61                           Linking your sprite areas
  62
  63         Sprinkle simply extends the functionality of OS_SpriteOp.  It doesn't
  64         have any SWIs of its own.  It makes use of a special part of the
  65         sprite area definition called the `extension area', which as far as
  66         I can make out is not defined anywhere.
  67
  68         You identify a sprite area as being linked by putting the following
  69         data into the extension area:
  70
  71                 Offset  Size    Value
  72                 0       4       &4B4C5053 (`SPLK')
  73                 4       4       Address of next sprite area, or 0
  74
  75         The list is terminated either by a sprite area which doesn't
  76         have this data in its extension area, or by a 0 pointer in its
  77         link word.
  78
  79         Loading a sprite file into an area and allowing it to be linked is
  80         fairly simple:
  81
  82         [In basic]
  83
  84         SYS "OS_File",17,name$ TO ,,,,sz%
  85         DIM blk% sz%+16
  86         blk%!0=sz%
  87         SYS "OS_File",16,name$,blk%+4+8,0
  88         blk%!4=blk%!12
  89         blk%!8=24
  90         blk%!12=blk%!20+8
  91         $(blk%+16)="SPLK"
  92         blk%!20=0
  93
  94         [In assembler]
  95
  96         ; On entry:     R0 == pointer to filename
  97
  98                         MOV     R1,R0
  99                         MOV     R0,#17
 100                         SWI     OS_File
 101                         ADD     R0,R4,#16
 102                         BL      alloc    ;allocate r0 bytes, return in r0
 103                         STMFD   R13!,{R0}
 104                         ADD     R2,R0,#12
 105                         MOV     R3,#0
 106                         MOV     R0,#16
 107                         SWI     OS_File
 108                         LDMFD   R13!,{R0}
 109                         ADD     R14,R0,#12
 110                         LDMIA   R14,{R1-R3}
 111                         MOV     R2,#24
 112                         ADD     R3,R3,#8
 113                         LDR     R4,=&4B4C5053
 114                         MOV     R5,#0
 115                         ADD     R14,R0,#4
 116                         STMIA   R14,{R1-R5}
 117
 118         ; On exit:      R0 == pointer to area
 119         ;               R1-R5, R14 corrupted
 120
 121         (Obviously you need to do some more error checking than this code
 122         has done.)
 123
 124 _____________________________________________________________________________
 125
 126
 127                                  Restrictions
 128
 129         Sprinkle isn't intended for really heavy use -- ensuring that all
 130         the OS_SpriteOp calls worked exactly as expected on linked areas
 131         would be fairly prohibitive in terms of effort.  Instead, it does
 132         a `reasonable' job on the read-only SpriteOp calls.  It provides
 133         enough support to allow you to use sprites from linked areas in
 134         your dialogue boxes, and that's about it.  If you do try writing-
 135         type operations which don't have enough memory, they will probably
 136         fail with strange errors (like `Sprite not found').
 137
 138 _____________________________________________________________________________