home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / libraries / ilbm / basic / basicusers < prev    next >
Text File  |  1991-02-15  |  12KB  |  260 lines
  1.                          FOR BASIC PROGRAMMERS
  2.  
  3.   The ilbm library operates on several structures. A structure is one block
  4. of memory which contains various "fields". A field is simply a portion (some
  5. bytes) of that block of memory. One structure that the ilbm library uses is
  6. an ILBMFrame. This structure takes up 172 bytes of memory. These 172 bytes
  7. contain 94 fields. Some fields only take up 1 byte, others are 2 bytes wide
  8. (a WORD), or 4 bytes wide (a LONG). Certain other fields can be any number
  9. of bytes wide. These are STRINGS. Each field of a structure contains values
  10. (numbers). Sometimes these numbers form the address of some other structure.
  11. An address takes up 4 bytes (just like a LONG), but we'll call it APTR.
  12. We can further differentiate between a BYTE and UBYTE, WORD and UWORD, and
  13. a LONG and ULONG. The prepended U means that this field is unsigned (i.e.
  14. don't ever store a negative number in this field).
  15.   Unfortunately, AmigaBasic has no facility for manipulating structures as
  16. such. You cannot say, "Set the iFLags field of my ILBMFrame to the value 1."
  17. You must treat the ILBMFrame as one block of memory, and its various fields
  18. as offsets from the beginning of that block of memory. You can allocate
  19. structures (blocks of mem) with the Exec library's AllocMem function which
  20. returns the start address of the mem block. Here is what an ILBMFrame would
  21. look like in memory.
  22.  
  23.   Field Name      Field Size       Offset from start
  24.  ------------    -------------    -------------------
  25.  
  26. The ILBMFrame starts here:
  27. iFlags            1 UBYTE                 0
  28. iUserFlags        1 UBYTE                 1
  29. iBMHD.w           2 BYTES (UWORD)         2
  30. iBMHD.h           2 BYTES (UWORD)         4
  31. iBMHD.x           2 BYTES (WORD)          6
  32. iBMHD.y           2 BYTES (WORD)          8
  33. iBMHD.nPlanes     1 UBYTE                10
  34. iBMHD.Masking     1 UBYTE                11
  35. iBMHD.Compression 1 UBYTE                12
  36. iBMHD.Pad         1 UBYTE                13
  37. iBMHD.Transparent 2 UBYTES (UWORD)       14
  38. iBMHD.xAspect     1 UBYTE                16
  39. iBMHD.yAspect     1 UBYTE                17
  40. iBMHD.pageWidth   2 BYTES (WORD)         18
  41. iBMHD.pageHeight  2 BYTES (WORD)         20
  42. iViewModes        4 BYTES (ULONG)        22
  43. iColorTable1      2 BYTES (UWORD)        26
  44. iColorTable2      2 BYTES (UWORD)        28
  45. iColorTable3      2 BYTES (UWORD)        30
  46. iColorTable4      2 BYTES (UWORD)        32
  47. iColorTable5      2 BYTES (UWORD)        34
  48. iColorTable6      2 BYTES (UWORD)        36
  49. iColorTable7      2 BYTES (UWORD)        38
  50. iColorTable8      2 BYTES (UWORD)        40
  51. iColorTable9      2 BYTES (UWORD)        42
  52. iColorTable10     2 BYTES (UWORD)        44
  53. iColorTable11     2 BYTES (UWORD)        46
  54. iColorTable12     2 BYTES (UWORD)        48
  55. iColorTable13     2 BYTES (UWORD)        50
  56. iColorTable14     2 BYTES (UWORD)        52
  57. iColorTable15     2 BYTES (UWORD)        54
  58. iColorTable16     2 BYTES (UWORD)        56
  59. iColorTable17     2 BYTES (UWORD)        58
  60. iColorTable18     2 BYTES (UWORD)        60
  61. iColorTable19     2 BYTES (UWORD)        62
  62. iColorTable20     2 BYTES (UWORD)        64
  63. iColorTable21     2 BYTES (UWORD)        66
  64. iColorTable22     2 BYTES (UWORD)        68
  65. iColorTable23     2 BYTES (UWORD)        70
  66. iColorTable24     2 BYTES (UWORD)        72
  67. iColorTable25     2 BYTES (UWORD)        74
  68. iColorTable26     2 BYTES (UWORD)        76
  69. iColorTable27     2 BYTES (UWORD)        78
  70. iColorTable28     2 BYTES (UWORD)        80
  71. iColorTable29     2 BYTES (UWORD)        82
  72. iColorTable30     2 BYTES (UWORD)        84
  73. iColorTable31     2 BYTES (UWORD)        86
  74. iColorTable32     2 BYTES (UWORD)        88
  75. iNumColors        1 UBYTE                90
  76. iCycleCnt         1 UBYTE                91
  77. iCRNG1.Pad        2 BYTES (WORD)         92
  78. iCRNG1.Rate       2 BYTES (WORD)         94
  79. iCRNG1.Active     2 BYTES (WORD)         96
  80. iCRNG1.Low        1 UBYTE                98
  81. iCRNG1.High       1 UBYTE                99
  82. iCRNG2.Pad        2 BYTES (WORD)        100
  83. iCRNG2.Rate       2 BYTES (WORD)        102
  84. iCRNG2.Active     2 BYTES (WORD)        104
  85. iCRNG2.Low        1 UBYTE               106
  86. iCRNG2.High       1 UBYTE               107
  87. iCRNG3.Pad        2 BYTES (WORD)        108
  88. iCRNG3.Rate       2 BYTES (WORD)        110
  89. iCRNG3.Active     2 BYTES (WORD)        112
  90. iCRNG3.Low        1 UBYTE               114
  91. iCRNG3.High       1 UBYTE               115
  92. iCRNG4.Pad        2 BYTES (WORD)        116
  93. iCRNG4.Rate       2 BYTES (WORD)        118
  94. iCRNG4.Active     2 BYTES (WORD)        120
  95. iCRNG4.Low        1 UBYTE               122
  96. iCRNG4.High       1 UBYTE               123
  97. iCRNG5.Pad        2 BYTES (WORD)        124
  98. iCRNG5.Rate       2 BYTES (WORD)        126
  99. iCRNG5.Active     2 BYTES (WORD)        128
  100. iCRNG5.Low        1 UBYTE               130
  101. iCRNG5.High       1 UBYTE               131
  102. iCRNG6.Pad        2 BYTES (WORD)        132
  103. iCRNG6.Rate       2 BYTES (WORD)        134
  104. iCRNG6.Active     2 BYTES (WORD)        136
  105. iCRNG6.Low        1 UBYTE               138
  106. iCRNG6.High       1 UBYTE               139
  107. iCRNG7.Pad        2 BYTES (WORD)        140
  108. iCRNG7.Rate       2 BYTES (WORD)        142
  109. iCRNG7.Active     2 BYTES (WORD)        144
  110. iCRNG7.Low        1 UBYTE               146
  111. iCRNG7.High       1 UBYTE               147
  112. iCRNG8.Pad        2 BYTES (WORD)        148
  113. iCRNG8.Rate       2 BYTES (WORD)        150
  114. iCRNG8.Active     2 BYTES (WORD)        152
  115. iCRNG8.Low        1 UBYTE               154
  116. iCRNG8.High       1 UBYTE               155
  117. iWindow           4 BYTES (APTR)        156
  118. iScreen           4 BYTES (APTR)        160
  119. iBMAP             4 BYTES (APTR)        164
  120. iBmSize           4 BYTES (ULONG)       168
  121.  
  122.   If you add up the sizes of all 94 fields, you should get 172 bytes.
  123.  
  124.   Now, let's say that we allocated an ILBMFrame via AllocMem as demonstrated
  125. in the example program, BasicILBM. We stored the returned address in a varia-
  126. ble called ILBMFrame.
  127.   There are two AmigaBASIC commands that are used with structures, PEEK and
  128. POKE. If you want to change a field of the ILBMFrame, you must POKE a value
  129. to it. If you want to know what value is already stored in an ILBMFrame
  130. field, then you PEEK that field. For example, if we want to know what the
  131. ILBMFrame's iNumColors field is, we PEEK that field as follows.
  132.  
  133.   VALUE = PEEK(ILBMFrame+90)
  134.  
  135.   I had to add 90 to ILBMFrame because the iNumColors field's offset is 90
  136. (see above chart). Now VALUE is the number that was in the iNumColors field.
  137. If we want to change the number in the iNumColors field to 2, we must POKE
  138. the field like this:
  139.  
  140.   POKE  ILBMFrame+90,2
  141.  
  142.   PEEK and POKE are used for fields that are only 1 BYTE in size (like the
  143. iNumColors, iFlags, etc). For fields that are 2 BYTES (WORD) in size, you
  144. must use POKEW and PEEKW.
  145.  
  146.   For LONG and APTR fields (4 BYTES in size), you must use PEEKL and POKEL.
  147. For example, to get the value in the iViewModes field we do the following:
  148.  
  149.   VALUE = PEEKL(ILBMFrame+22)
  150.  
  151.   Notice how I added the iViewModes field's offset to ILBMFrame.
  152.  
  153. An APTR field is tricky because you can only put an address there. There are
  154. two BASIC commands for finding addresses of variables. If the variable is a
  155. string, use SADD. For all other types of variables, use VARPTR.
  156.  
  157.   A & appended to a variable indicates that the variable is to be a 32 bit
  158. value. All variables used in calls to the ilbm library must be declared as
  159. 32 bit values. Alternately, you can force all variables in your program to
  160. 32 bits by using the statement:
  161.  
  162.   DEFLNG a-Z
  163.  
  164.   This is easier than "casting" each individual variable used in lib calls,
  165. but is more memory intensive.
  166.  
  167.   Please see the documentation for the requester lib for further discussion of
  168. SADD and VARPTR.
  169.  
  170.   There is much more to be said about this topic. Please examine the commented
  171. code of the enclosed BASIC example. If the code seems completely alien to you,
  172. then you should buy a book on advanced AmigaBASIC programming. I can't recom-
  173. mend one as I didn't read any. Being an assembly programmer, I was able to
  174. ascertain how to use these BASIC commands by studying an example on the EXTRAS
  175. disk.
  176.  
  177.   There is one ILBMFrame field that the example only briefly covers, the
  178. iUserFlags field. Here are the values you should POKE to enable the following
  179. features. To enable several features simultaneously, just add up the values
  180. for each.
  181.  
  182.  Feature        Value
  183.  ­­­­­­­       ­­­­­­­
  184. NO_POINTER       = 1   (bit # 0 - Set means no visible pointer)
  185. NO_TITLE_BAR     = 2   (bit # 1 - Set means hide screen title)
  186. NO_LOAD_COLORS   = 4   (bit # 2 - Set means don't change the present screen
  187.                         colors)
  188. NO_SCALE         = 8   (bit # 3 - Set means don't scale a picture to fit a
  189.                         different size screen, just crop it)
  190.  
  191.  
  192. ANIM_FILE        = 128  This is is only turned on by the lib. You should
  193.                         turn it off before every load, by initializing the
  194.                         entire iUserFlags field without this enabled, or
  195.                         by turning off this one flag as demonstrated below.
  196.  
  197.   After returning from LoadIFFToWindow, if the iUserFlags field is > 127,
  198. then the image loaded was the first frame of an ANIM file.
  199.   Each "feature" in the iUserFlags field is its own bit, so you can PEEK the
  200. iFlags field and use the AND and OR Basic commands to determine whether a
  201. feature is enabled or not. For example, let's isolate the NO_TITLE_BAR bit
  202. and see if its on:
  203.  
  204.   flag = PEEK(ILBMFrame+22) 'Get the present value
  205.   flag = 2 AND flag         '2 is the value of NO_TITLE_BAR flag
  206.   IF flag = 2 THEN PRINT "NO_TITLE_BAR is on"  'flag = 0 if its off
  207.  
  208.  
  209.   Now let's turn off the ANIM_FILE bit without affecting the other bits.
  210.  
  211.   flag = PEEK(ILBMFrame+22)  'Get the present value
  212.   value = 128                'This is the value for the ANIM_FILE flag
  213.   value = NOT value          'To turn off the ANIM_FILE we need to NOT this
  214.   flag  = value AND flag     'We just made sure that ANIM_FILE bit is off
  215.                              'without affecting the other bits.
  216.   POKE   ILBMFrame+22,flag   'store the new iUserFlags
  217.  
  218.  
  219.   Finally, let's turn on the NO_LOAD_COLORS without affecting the others.
  220.  
  221.   flag = PEEK(ILBMFrame+22)  'Get the present value
  222.   value = 4                  'This is the value for the NO_LOAD_COLORS flag
  223.   flag  = value OR flag      'We just turned on NO_LOAD_COLORS
  224.                              'without affecting the other bits.
  225.   POKE   ILBMFrame+22,flag   'store the new iUserFlags
  226.  
  227.  
  228.   Of course, read the enclosed Doc file fully for a complete understanding
  229. of the ilbm library functions.
  230.  
  231.   Also, the examples utilize a file selection requester which is also a public
  232. domain library on this disk. All the documentation is in FileIO. In that Basic
  233. example, there are a couple things that I need to correct. At the label,
  234. CheckError, change the code to this:
  235.  
  236. CheckError:
  237.    IF Result <> 0 THEN GOTO GotPathname
  238.    Result=AutoFileMessage(0&,WINDOW(7))
  239.    INPUT "Type path:";Pathname$
  240.    CALL ParseString(FileIO,SADD(Pathname$))
  241.    GOTO CopyFN
  242.  
  243.  Also, in my comments about reading and writing files, I neglected to place
  244. the Basic command CALL before certain lib calls. Change them thus:
  245.  
  246.    CALL  WaitPointer(WINDOW(7))
  247.    CALL  ClearPointer(WINDOW(7))
  248.  
  249.   In these same comments, I used Error as a variable name. This is a reserved
  250. command in AmigaBasic. Change all occurences of Error to some other variable
  251. name.
  252.  
  253.   On final note to Basic users: I gave this lib to a friend who was using
  254. C. Scheppner's Basic ilbm loading code in his program. Not only did the
  255. load procedure time decrease dramatically, but he claims that his program
  256. size dropped 140K mostly due to all of the variable storage required by the
  257. replaced basic ilbm code.
  258.  
  259.           Jeff Glatt
  260.