home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / dev / cmanual-3.0.lha / CManual / Graphics / VSprites / VSprites.doc < prev    next >
Text File  |  1993-10-12  |  29KB  |  1,022 lines
  1. 4    VSPRITES
  2.  
  3. 4.1  INTRODUCTION
  4.  
  5. VSprites, or Virtual Sprites as their whole name is, are very
  6. similar to Hardware Sprites. VSprites have the same limitations
  7. such as a maximum width of 16 pixels and can only use three
  8. colours (actually four colours, but the first colour will act
  9. as transparent.) However, VSprites are superior to Hardware
  10. Sprites because you may use much more than eight VSprites at
  11. the same time, and each VSprite may use its own three colours
  12. out of a palette of 4096 colours. The disadvantage with
  13. VSprites compared to Hardware Sprites is that Hardware Sprites
  14. are totally controlled by the hardware and thus very fast,
  15. while VSprites are partly controlled by the software and
  16. because of that a bit slower.
  17.  
  18.  
  19.  
  20. 4.2  HOW VSPRITES WORK
  21.  
  22. The reason why VSprites are so similar to Hardware Sprites is
  23. that VSprites are actually displayed with help of Hardware
  24. Sprites. If you want a VSprite to be at the top of the display
  25. and one further down, the system will position a Hardware Sprite
  26. at the top and change its image so it correspond to the
  27. VSprites image. The colours will also automatically be changed
  28. by altering the Copper List. (See chapter "Hacks" for more
  29. information about the Copper list.)
  30.  
  31. When the video beam has passed the first VSprite, the Hardware
  32. Sprite is not needed there any more and can therefore be used
  33. again. The system can therefore use the same Hardware Sprite to
  34. display another VSprite, and so on. Because of this you can have
  35. much more than eight sprites at the same time on the display.
  36.  
  37. If two or more VSprites would be on the same height, more
  38. Hardware Sprites are needed. The system has eight Hardware
  39. Sprites as its disposal, and can therefore display up to
  40. eight VSprites on the same line.
  41.  
  42. Here is an example. You want to display three VSprites
  43. positioned as below. In this case two Hardware Sprites are
  44. needed. Hardware Sprite one is used to display VSprite A
  45. and B. A and B are not on the same height, and only one
  46. Hardware Sprite is therefore needed. However, VSprite C
  47. is on the same lines as B, and a second Hardware Sprite is
  48. therefore needed.
  49.  
  50.   -----
  51.   | A |
  52.   -----
  53.     -----
  54.     | B |    -----
  55.     -----    | C |
  56.              -----
  57.  
  58.  
  59.  
  60. 4.2.1  LIMITATIONS
  61.  
  62. There are some important limitations that you need to remember:
  63.  
  64. 1. If you have reserved some Hardware Sprites for your own
  65.    use, the system can not use these sprites and this will
  66.    limit the maximum numbers of VSprites on the same height.
  67.  
  68. 2. Hardware Sprites 0 and 1, 2 and 3, 4 and 5, 6 and 7 share
  69.    the same colours. If sprite 0 is used to display one
  70.    VSprite, the computer can not use sprite 1 to display
  71.    another VSprite on the same height if it has different
  72.    colours. Because of that there is a limitation of a
  73.    maximum of four VSprites with different colours on the
  74.    same height.
  75.  
  76. 3. If you display the VSprites on a screen with a depth of 5
  77.    or more (32 colours or more) you will see strange colour
  78.    fluctuations on the lines where the VSprites are. The
  79.    reason is that VSprites are now using the same colour
  80.    register as the display, and as we said before, the system
  81.    is all the time changing these colours to match the
  82.    VSprites' colours.
  83.  
  84. If the system can not find a Hardware Sprite to display a
  85. VSprite because of the limitations above, the VSprite will
  86. simply not be drawn.
  87.  
  88.  
  89.  
  90. 4.2.2  HOW TO AVOID THE LIMITATIONS
  91.  
  92. There are several guidelines to follow in order to avoid the
  93. limitations:
  94.  
  95. 1. Use as few VSprites as possible on the same lines.
  96. 2. Try to use VSprites with the same colours.
  97. 3. If you are using a display with more than 16 colours, you
  98.    should only use colour 16, 20, 24, and 28. (These are the
  99.    transparent colours, and will therefore not be changed.)
  100.  
  101.  
  102.  
  103. 4.3  CREATE VSPRITES
  104.  
  105. IF YOU WANT TO USE VSPRITES YOU HAVE TO
  106. ---------------------------------------------------------------
  107.  1. Declare and initialize some sprite data for each VSprite.
  108.  2. Declare a VSprite structure for each VSprite plus two extra
  109.     structures for two dummy VSprites.
  110.  3. Decide each VSprite's colours.
  111.  4. Declare a GelsInfo structure.
  112.  5. Open the Graphics Library.
  113.  6. Initialize the GelsInfo structure.
  114.  7. Initialize the VSprite structure.
  115.  8. Add the VSprites to the VSprite list.
  116.  9. Sort the Gels list. SortGList()
  117. 10. Draw the Gels list. DrawGList()
  118. 11. Set the Copper and redraw the display.
  119.     [ MrgCop() and LoadView() or        ]
  120.     [ MakeScreen() and RethinkDisplay() ]    
  121. 12. Play around with the VSprites.
  122. 13. Remove the VSprites. RemVSprite()
  123.  
  124. (Easy, isn't it?)
  125.  
  126.  
  127.  
  128. 4.3.1  VSPRITE DATA
  129.  
  130. Sprite data for VSprites is declared and initialized as normal
  131. sprite data. Just remember that all sprite data must be placed
  132. in Chip memory.
  133.  
  134. Example:
  135.  
  136.   UWORD chip vsprite_data[]=
  137.   {
  138.     0x0FF0, 0x0FF0,
  139.     0x0FF0, 0x0FF0,
  140.     0x0FF0, 0x0FF0,
  141.     0x0FF0, 0x0FF0
  142.   };
  143.  
  144.  
  145.  
  146. 4.3.2  VSPRITE STRUCTURE
  147.  
  148. You need to declare a VSprite structure for each VSprite you
  149. are going to use, and two extra for two "dummy VSprites". The
  150. two dummy VSprites are used by the gel system (GEL stands for
  151. Graphic ELements). (One of the two dummy sprites is placed
  152. first in the gel-list, and the other one is placed last. The
  153. gel system can then sort the list much faster, and speed is
  154. essential here.)
  155.  
  156. Example:
  157.  
  158.   struct VSprite head, tail, vsprite;
  159.  
  160.  
  161. The VSprite structure looks like this: [Declared in the header
  162. file "graphics/gels.h".]
  163.  
  164. struct VSprite
  165. {
  166.   struct VSprite *NextVSprite;
  167.   struct VSprite *PrevVSprite;
  168.   struct VSprite *DrawPath;
  169.   struct VSprite *ClearPath;
  170.  
  171.   WORD OldY, OldX;
  172.   WORD Flags;
  173.   WORD Y, X;
  174.   WORD Height;
  175.   WORD Width;
  176.   WORD Depth;
  177.   WORD MeMask;
  178.   WORD HitMask;
  179.   WORD *ImageData;
  180.   WORD *BorderLine;
  181.   WORD *CollMask;
  182.   WORD *SprColors;
  183.   struct Bob *VSBob;
  184.   BYTE PlanePick;
  185.   BYTE PlaneOnOff;
  186.   VUserStuff VUserExt;
  187. };
  188.  
  189.  
  190. NextVSprite: Pointer to the next VSprite in the list.
  191.  
  192. PrevVSprite: Pointer to the previous VSprite in the list.
  193.  
  194. DrawPath:    Used by BOBs.
  195.  
  196. ClearPath:   Used by BOBs.
  197.  
  198. OldY:        Previous Y position.
  199.  
  200. OldX:        Previous X position.
  201.  
  202. Flags:       Following flags may be set by the user:
  203.                SUSERFLAGS Mask of the user settable flags.
  204.                VSPRITE    Set this flag if you are using the
  205.                           structure for a VSprite.
  206.                MUSTDRAW   Set this flag if this VSprite must
  207.                           be drawn.
  208.                           Following flags are set by the system:
  209.                GELGONE    This flag is set if the VSprite is
  210.                           outside the
  211.                VSOVERFLOW Too many VSprites on the same lines.
  212.                           If the flag MUSTDRAW is set, the
  213.                           system will try to draw it, but it
  214.                           could look strange.
  215.  
  216. Y:           Y position.
  217.  
  218. X:           X position.
  219.  
  220. Height:      The height of the VSprite.
  221.  
  222. Width:       Number of words used for each line. For the moment
  223.              a VSprite can only be 16 pixels wide, which means
  224.              two words. 
  225.  
  226. Depth:       Number of planes. A VSprite can for the moment
  227.              only use two planes, 3 colours and one transparent.
  228.  
  229. MeMask:      What can collide with this VSprite. (Will be
  230.              explained in a future version of the manual.)
  231.  
  232. HitMask:     What this VSprite can collide with. (Will be
  233.              explained in a future version of the manual.)
  234.  
  235. ImageData:   Pointer to the sprite data.
  236.  
  237. BorderLine:  (Will be explained in a future version of the manual.)
  238.  
  239.  
  240. CollMask:    (Will be explained in a future version of the manual.)
  241.  
  242. SprColors:   Pointer to a colour table for this VSprite.
  243.  
  244. VSBob:       Used if it is a BOB. (Will be explained in a future
  245.              version of the manual.)
  246.  
  247. PlanePick:   Used if it is a BOB. (Will be explained in a future
  248.              version of the manual.)
  249.  
  250. PlaneOnOff:  Used if it is a BOB. (Will be explained in a future
  251.              version of the manual.)
  252.  
  253. VUserExt:    You may use this as you please. Here you can add
  254.              extra information etc. (Is actually declared as a
  255.              SHORT variable.)
  256.  
  257.  
  258.  
  259. 4.3.3  COLOUR TABLE
  260.  
  261. Each VSprite can have its own three colours out of a palette
  262. of 4096. The three desired col