home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / dev / cmanual-3.0.lha / CManual-3.0 / Graphics / Sprites / Sprites.doc < prev    next >
Encoding:
Text File  |  1993-10-12  |  25.6 KB  |  871 lines
  1. 3    SPRITES
  2.  
  3. 3.1  INTRODUCTION
  4.  
  5. Sprites are small objects that can be moved around the
  6. display without changing the background. The Amiga has eight
  7. DMA channels which allows us to use 8 Hardware Sprites. The
  8. advantages of using hardware sprites is that they can be moved
  9. around, animated etc without interfering with the main
  10. processor (CPU). They are therefore extremely fast to move,
  11. and also very easy to handle.
  12.  
  13. Sprites can be used in many situations. If you make a game you
  14. can use the sprites as aliens, missiles, explosion etc. Even
  15. now, when you are reading this, a sprite is used. Intuition's
  16. Pointer is actually a sprite as described in chapter 2 WINDOWS.
  17.  
  18.  
  19.  
  20. 3.2  LIMITATIONS
  21.  
  22. Sprites are wonderful small things but there exist some
  23. limitations:
  24.  
  25. 1. Sprites may only be up to 16 pixels wide. (There is no
  26.    limit on how tall they may be.) (Sprites are always using
  27.    low-resolution pixels. Even if you have a high-resolution
  28.    screen, the sprites will only be in low resolution. This
  29.    shows how independent sprites are.)
  30.  
  31. 2. Each sprite can only use three colours + one "transparent"
  32.    colour.
  33.  
  34. 3. There are only eight hardware sprites. 
  35.  
  36. These limitations can be avoided:
  37.  
  38. 1. You can place two or more sprites side by side in order
  39.    to make the object wider than 16 pixels.
  40.  
  41. 2. You can "connect" two sprites and boast the number of
  42.    available colours from 3 to 15 plus one transparent.
  43.  
  44. 3. It is possible to reuse each hardware sprite to "plop" out
  45.    several sprites (VSprites) on the display.
  46.  
  47.  
  48.  
  49. 3.3  COLOURS
  50.  
  51. Each sprite may have three different colours plus one
  52. transparent colour. Sprite zero and one will use colour
  53. register 16-19, sprite two and three will use colour register
  54. 20-23 and so on:
  55.  
  56. Sprite    Colour Register
  57. -----------------------------------
  58. 0 and 1   16 - 19  (16 transparent)
  59. 2 and 3   20 - 23  (20     -"-    )
  60. 4 and 5   24 - 27  (24     -"-    )
  61. 6 and 7   28 - 31  (28     -"-    )
  62.  
  63. Two important thing to remember:
  64.  
  65. 1. The sprites 0 and 1, 2 and 3, 4 and 5, 6 and 7, use the
  66.    same colour registers. If you change colour register 17,
  67.    both sprite zero and one will be affected.
  68.  
  69. 2. If you have a low-resolution screen with a depth of 5 (32
  70.    colours), the last 16 colours will be shared between the
  71.    sprites and the screen. However, if you only use a 16
  72.    coloured screen (depth 4) you still use the top sixteen
  73.    colour registers for the sprites. That means you can have
  74.    a 16 coloured screen, and still use another 16 colours for the
  75.    sprites.
  76.  
  77. Colour register 16, 20, 24 and 28 are "transparent" which
  78. means that the background colour of the screen will shine
  79. through. Those registers can have any kind of colours since
  80. they will not affect the sprites.
  81.  
  82.  
  83.  
  84. 3.4  ACCESS HARDWARE SPRITES
  85.  
  86. If you want to use a hardware sprite you need to:
  87.  
  88. 1. Declare and initialize some sprite graphics data.
  89.  
  90. 2. Declare and initialize a SimpleSprite structure.
  91.  
  92. 3. Call the function GetSprite() with a pointer to your
  93.    SimpleSprite structure, plus a request for which sprite
  94.    you want, as parameters.
  95.  
  96. 4. Move the sprite around by calling the function MoveSprite()
  97.    and animate it by changing the sprite graphics
  98.    (ChangeSprite()).
  99.  
  100. 5. Return the sprite to the hardware when you do not need it
  101.    anymore, by calling the function FreeSprite().
  102.  
  103.  
  104.  
  105. 3.4.1  SPRITE DATA
  106.  
  107. We have already described how to create your own sprite data
  108. in chapter 2 WINDOWS, but here is a short summary:
  109.  
  110. [A] The first thing you need to do is to draw on a paper how
  111.     the sprite should look like. Remember that the sprite may
  112.     only be 16 pixels wide, but any height. (You can of course
  113.     put two sprites beside each other if you need a sprite
  114.     which is wider than 16 pixels). Remember also that you
  115.     may only use three colours/sprite (described above).
  116.     
  117.     Imagine that you have come up with a suggestion like this:
  118.     
  119.     0000000110000000    0: Transparent
  120.     0000001111000000    1: Red
  121.     0000011111100000    2: Yellow
  122.     0000111111110000    3: Green
  123.     0001111111111000
  124.     0011111111111100
  125.     0111111111111110
  126.     2222222222222222
  127.     2222222222222222
  128.     0333333333333330
  129.     0033333333333300
  130.     0003333333333000
  131.     0000333333330000
  132.     0000033333300000
  133.     0000003333000000
  134.     0000000330000000
  135.  
  136.  
  137. [B] You now need to translate this into Sprite Data. Each
  138.     line of the graphics will be translated into two words
  139.     of data. The first word represents the first Bitplane,
  140.     and the second word the second Bitplane. The idea is that
  141.     if you want colour 0 both Bitplane zero and one should be
  142.     0, if you want colour 1 Bitplane zero should be 1 and
  143.     Bitplane one 0 and so on:
  144.  
  145.     Colour  Bitplane One  Bitplane Zero          Since
  146.     ----------------------------------------------------------
  147.     0       0             0               Binary 00 = Colour 0
  148.     1       0             1                  "   01 =    "   1
  149.     2       1             0                  "   10 =    "   2
  150.     3       1             1                  "   11 =    "   3
  151.  
  152.     The data for the pointer would then look like this:
  153.  
  154.     Bitplane ZERO      Bitplane ONE
  155.  
  156.     0000000110000000   0000000000000000
  157.     0000001111000000   0000000000000000
  158.     0000011111100000   0000000000000000
  159.     0000111111110000   0000000000000000
  160.     0001111111111000   0000000000000000
  161.     0011111111111100   0000000000000000
  162.     0111111111111110   0000000000000000
  163.     0000000000000000   1111111111111111
  164.     0000000000000000   1111111111111111
  165.     0111111111111110   0111111111111110
  166.     0011111111111100   0011111111111100
  167.     0001111111111000   0001111111111000
  168.     0000111111110000   0000111111110000
  169.     0000011111100000   0000011111100000
  170.     0000001111000000   0000001111000000
  171.     0000000110000000   0000000110000000
  172.  
  173.  
  174. [C] The last step is to translate the binary numbers to type
  175.     UWORD. Group the binary number in four and translate it to
  176.     Hexadecimal:
  177.  
  178.     Binary  Hexadecimal
  179.     -------------------
  180.     0000 =  0
  181.     0001 =  1
  182.     0010 =  2
  183.     0011 =  3
  184.     0100 =  4
  185.     0101 =  5
  186.     0110 =  6
  187.     0111 =  7
  188.     1000 =  8
  189.     1001 =  9
  190.     1010 =  A
  191.     1011 =  B
  192.     1100 =  C
  193.     1101 =  D
  194.     1110 =  E
  195.     1111 =  F
  196.  
  197.     The result will look like this:
  198.  
  199.     ONE:    TWO:
  200.     ------------
  201.     0180    0000      0000 0001 1000 0000  0000 0000 0000 0000
  202.     03C0    0000      0000 0011 1100 0000  0000 0000 0000 0000
  203.     07E0    0000      0000 0111 1110 0000  0000 0000 0000 0000
  204.     0FF0    0000      0000 1111 1111 0000  0000 0000 0000 0000
  205.     1FF8    0000      0001 1111 1111 1000  0000 0000 0000 0000
  206.     3FFC    0000      0011 1111 1111 1100  0000 0000 0000 0000
  207.     7FFE    0000      0111 1111 1111 1110  0000 0000 0000 0000
  208.     0000    FFFF      0000 0000 0000 0000  1111 1111 1111 1111
  209.     0000    FFFF      0000 0000 0000 0000  1111 1111 1111 1111
  210.     7FFE    7FFE      0111 1111 1111 1110  0111 1111 1111 1110
  211.     3FFC    3FFC      0011 1111 1111 1100  0011 1111 1111 1100
  212.     1FF8    1FF8      0001 1111 1111 1000  0001 1111 1111 1000
  213.     0FF0    0FF0      0000 1111 1111 0000  0000 1111 1111 0000
  214.     07E0    07E0      0000 0111 1110 0000  0000 0111 1110 0000
  215.     03C0    03C0      0000 0011 1100 0000  0000 0011 1100 0000
  216.     0180    0180      0000 0001 1000 0000  0000 0001 1000 0000
  217.  
  218.  
  219. [D] Since the Amiga need to store the position of the sprite,
  220.     the size etc, you should also declare two empty words at
  221.     the top, and to empty words at the bottom of the Sprite
  222.     data. These words will be initialized and maintained by
  223.     Intuition, so you do not need to bother about them.
  224.  
  225.     A declaration and initialization of the sprite data would
  226.     therefore be:
  227.  
  228.     UWORD chip my_sprite_data[36]=
  229.     {
  230.       0x0000, 0x0000,
  231.  
  232.       0x0180, 0x0000,
  233.       0x03C0, 0x0000,
  234.       0x07E0, 0x0000,
  235.       0x0FF0, 0x0000,
  236.       0x1FF8, 0x0000,
  237.       0x3FFC, 0x0000,
  238.       0x7FFE, 0x0000,
  239.       0x0000, 0xFFFF,
  240.       0x0000, 0xFFFF,
  241.       0x7FFE, 0x7FFE,
  242.       0x3FFC, 0x3FFC,
  243.       0x1FF8, 0x1FF8,
  244.       0x0FF0, 0x0FF0,
  245.       0x07E0, 0x07E0,
  246.       0x03C0, 0x03C0,
  247.       0x0180, 0x0180,
  248.       
  249.       0x0000, 0x0000
  250.     };
  251.  
  252.  
  253. IMPORTANT! Remember that all image data must as (always!) be
  254. loaded into the Chip memory (the lowest 512k of RAM). If you
  255. use Lattice C V5.00 or higher you can use the keyword chip in
  256. front of the image name. Check your compiler manual.
  257.  
  258.  
  259.  
  260. 3.4.2  SIMPLESPRITE STRUCTURE
  261.  
  262. The SimpleSprite structure look like this:
  263.  
  264. struct SimpleSprite
  265. {
  266.   UWORD *posctldata;
  267.   UWORD height;
  268.   UWORD x, y;
  269.   UWORD num;
  270. };
  271.  
  272. posctldata: Pointer to an array of UWORDs which is used for
  273.             the graphics of the sprite.
  274.  
  275. height:     Height of the sprite (lines). (Hardware Sprites
  276.             are always 16 pixels wide.)
  277.  
  278. x, y:       Position on the display relative to the ViewPort/
  279.             View (Display).
  280.  
  281. num:        Sprite number (0-7). When you call the GetSprite()
  282.             function it will automatically initialize this
  283.             field with the reserved sprite number, so set it
  284.             to -1 for the moment.
  285.  
  286.  
  287.  
  288.  
  289. 3.4.3  RESERVE A SPRITE
  290.  
  291. Before you may use a hardware sprite you must have reserved
  292. it. (Since the Amiga is multitasking it can happen that another
  293. program is using the sprite.) You reserve a sprite by calling
  294. the function GetSprite():
  295.  
  296. Synopsis:      sprite_got = GetSprite(my_sprite, sprite_wanted);
  297.  
  298. sprite_got:    (long) GetSprite() returns the number of the
  299.                sprite you got (0-7). If it could not get the
  300.                desired sprite, it returns -1. Remember to
  301.                check if you got the sprite you wanted! (the
  302.                SimpleSprite structure's num field will also
  303.                be initialized automatically.)
  304.  
  305. my_sprite:     (struct SimpleSprite *) Pointer to your
  306.                SimpleSprite structure.
  307.  
  308. sprite_wanted: (long) The number of the hardware sprite you
  309.                want to use (0-7). If it does not matter which
  310.                sprite you get you can write -1. (The System
  311.                will then give you any free hardware sprite.)
  312.  
  313.  
  314.  
  315. 3.4.4  PLAY WITH THE SPRITE
  316.  
  317. Once you have reserved a sprite you may start to play around
  318. with it. You move the sprite by calling the function
  319. MoveSprite():
  320.  
  321. Synopsis:  MoveSprite( view_port, my_sprite, x, y );
  322.  
  323. view_port: (struct ViewPort *) Pointer to the ViewPort which
  324.            this sprite is connected to, or 0 if the sprite
  325.            should be connected to the current View.
  326.  
  327. my_sprite: (struct SimpleSprite *) Pointer to your SimpleSprite
  328.            structure.
  329.  
  330. x, y:      (long) The new position on the display. (Sprites use
  331.            low-resolution pixels.)
  332.  
  333. For example, MoveSprite( 0, &my_sprite, 30, 50 ); moves the
  334. sprite (my_sprite) to position (30, 50). (Relative to the
  335. current View.)
  336.  
  337.  
  338. You can also change the image (sprite data) of the sprite in
  339. order to animate it. You simply call the function
  340. ChangeSprite() with a pointer to a new sprite data as a
  341. parameter, and the rest is done for you.
  342.  
  343. Synopsis:  ChangeSprite( view_port, my_sprite, new_data );
  344.  
  345. view_port: (struct ViewPort *) Pointer to the ViewPort which
  346.            this sprite is connected to, or 0 if the sprite is
  347.            connected to the current View.
  348.  
  349. my_sprite: (struct SimpleSprite *) Pointer to your SimpleSprite
  350.            structure.
  351.  
  352. new_data:  (short *) Pointer to the new sprite data.
  353.  
  354.  
  355.  
  356. 3.4.5  FREE THE SPRITE
  357.  
  358. When you do not need the sprite any more (when your program
  359. quits for example), you need to free the sprite so another task
  360. can use it if necessary. Important! You must free all sprites
  361. you have allocated, if not no other tasks can use them, and
  362. the only way to free the hardware is then to reset the machine.
  363. You free a sprite by calling the function FreeSprite():
  364.  
  365. Synopsis:   FreeSprite( sprite_got );
  366.  
  367. sprite_got: (long) The sprite you want to free (0-7).
  368.  
  369.  
  370.  
  371. 3.4.6  PROGRAM STRUCTURE
  372.  
  373. A program using sprites would look something like this:
  374.  
  375. /* Since we are using sprites we need to include this file: */
  376. #include <graphics/sprite.h>
  377.  
  378.  
  379. /* 1. Declare and initialize some sprite graphics data: */
  380. UWORD chip my_sprite_data[36]=
  381. {
  382.   0x0000, 0x0000,
  383.  
  384.   0x0180, 0x0000,
  385.   0x03C0, 0x0000,
  386.   0x07E0, 0x0000,
  387.   0x0FF0, 0x0000,
  388.   0x1FF8, 0x0000,
  389.   0x3FFC, 0x0000,
  390.   0x7FFE, 0x0000,
  391.   0x0000, 0xFFFF,
  392.   0x0000, 0xFFFF,
  393.   0x7FFE, 0x7FFE,
  394.   0x3FFC, 0x3FFC,
  395.   0x1FF8, 0x1FF8,
  396.   0x0FF0, 0x0FF0,
  397.   0x07E0, 0x07E0,
  398.   0x03C0, 0x03C0,
  399.   0x0180, 0x0180,
  400.  
  401.   0x0000, 0x0000
  402. };
  403.  
  404.  
  405. /* 2. Declare and initialize a SimpleSprite structure: */
  406. struct SimpleSprite my_sprite=
  407. {
  408.   my_sprite_data, /* posctldata, pointer to the sprite data. */
  409.   16,             /* height, 16 lines tall. */
  410.   40, 20,         /* x, y, position on the screen. */
  411.   -1,             /* num, this field is automatically   */
  412.                   /* initialized when we call the       */
  413.                   /* GetSprite() function, so we set it */
  414.                   /* to -1 for the moment.              */
  415. };
  416.  
  417.  
  418.  
  419. UWORD chip new_sprite_data[26]=
  420. {
  421.   0x0000, 0x0000,
  422.   and so on...
  423.  
  424.  
  425. main()
  426. {
  427.   /* Open the Graphics library etc... */
  428.   
  429.   
  430.   /* 3. Call the function GetSprite() with a pointer to */
  431.   /*    your SimpleSprite structure, plus a request for */
  432.   /*    which sprite you want, as parameters. Try to    */
  433.   /*    reserve sprite number 2:                        */
  434.   if( GetSprite( &my_sprite, 2 ) != 2 )
  435.   {
  436.     /* ERROR! */
  437.     /* Could not reserve sprite number 2. */
  438.   }
  439.  
  440.  
  441.   /* 4. Move the sprite around by calling the function */
  442.   /*    MoveSprite() and animate it by changing the    */
  443.   /*    sprite graphics by calling the function        */
  444.   /*    ChangeSprite().                                */
  445.  
  446.   /* Move the sprite to position (20, 30)
  447.   MoveSprite( 0, &my_sprite, 20, 30 );
  448.   
  449.   /* Change the sprite data: */
  450.   ChangeSprite( 0, &my_sprite, new_sprite_data );
  451.  
  452.  
  453.  
  454.   /* 5. Return the sprite to the hardware when you do not need it */
  455.   /*    anymore, by calling the function FreeSprite():            */
  456.   FreeSprite( my_sprite.num );
  457.  
  458.   /* Close other things etc... */
  459. }
  460.  
  461.  
  462.  
  463. 3.5  TECHNIQUES
  464.  
  465. Since both moving and changing the sprite is done by special
  466. hardware it goes with lightning speed without the main CPU
  467. even knowing about it. If you can you should use the sprites
  468. since the hardware is specialized in handling them. However,
  469. there are, as mentioned before, some limitations which can
  470. cause some problems, but by using some special techniques you
  471. can manage almost anything. Sprites can also be used to create
  472. some interesting special effects, and are perfect to animate.
  473.  
  474.  
  475.  
  476. 3.5.1  WIDER SPRITES
  477.  
  478. If you want a space ship top be 32 pixels wide you can use
  479. two sprites side by side in order to get the desired effects.
  480. Every time you move the ship you call the MoveSprite() function
  481. twice. Since sprites are moved so fast the user will never
  482. realize that the ship is built up of two sprites.
  483.  
  484. (30,50)        (30+16, 50)
  485.     *--------------*----------------
  486.     |          ####|####           |
  487.     |         #   #|#  ##          |
  488.     | #############|############## |
  489.     |##############|###############|
  490.     | #############|############## |
  491.     --------------------------------
  492.         Sprite 2       Sprite 3
  493.  
  494. If you use all eight sprites you can get an image which is
  495. 128 pixels wide and any height. I do not think you need a
  496. bigger ship than that.
  497.  
  498.  
  499.  
  500. 3.5.2  MORE COLOURS
  501.  
  502. Each sprite may only use three colours plus transparent.
  503. However, it is possible to connect two sprites and be able
  504. to use 15 colours plus transparent. (Since each sprite use two
  505. Bitplanes, it means that an attached sprite has four Bitplanes
  506. which gives 16 combinations = 15 colours + 1 transparent.)
  507.  
  508. The sprites may be attached as follows:
  509.   1 to 0  (Set the SPRITE_ATTACHED bit in Sprite 1's sprite data)
  510.   3 to 2  (                  - " -               3    - " -     )
  511.   5 to 4  (                  - " -               5    - " -     )
  512.   7 to 6  (                  - " -               7    - " -     )
  513.  
  514. The even sprites (0, 2, 4 and 6) are called Bottom Sprites,
  515. while the odd sprites (1, 3, 5 and 7) are called Top Sprites.
  516.  
  517. When you want to use an attached sprite you need to:
  518.  
  519. 1. Declare and initialize two sprite data.
  520.  
  521. 2. Set the Attach bit (on the odd sprite 1, 3, 5 or 7) in
  522.    the second word of the sprite data.
  523.  
  524. 3. Once you have reserved both of the sprites, GetSprite(),
  525.    they can be moved around. It is important that both sprites
  526.    are moved together so the Attach mode works, otherwise they
  527.    will become three coloured sprites again.
  528.  
  529.  
  530.  
  531. 3.5.2.1  15 COLOURED SPRITE DATA
  532.  
  533. As you have seen before, the sprite data is built up of two
  534. bitplanes. When we attach two sprites we consequently get four
  535. Bitplanes, and therefore 15 colours plus transparent.
  536.  
  537. The Bottom Sprite contributes with Bitplane zero and one,
  538. while the Top Sprite contributes with Bitplane two and three.
  539.  
  540. So if you want the sprite to look like this:
  541.  
  542. 0000000000000000     0: Colour register 16 (Transparent)
  543. 1111111111111111     1:      - " -      17
  544. 2222222222222222     2:      - " -      18
  545. 3333333333333333     3:      - " -      19
  546. 4444444444444444     4:      - " -      20
  547. 5555555555555555     5:      - " -      21
  548. 6666666666666666     6:      - " -      22
  549. 7777777777777777     7:      - " -      23
  550. 8888888888888888     8:      - " -      24
  551. 9999999999999999     9:      - " -      25
  552. AAAAAAAAAAAAAAAA     A:      - " -      26
  553. BBBBBBBBBBBBBBBB     B:      - " -      27
  554. CCCCCCCCCCCCCCCC     C:      - " -      28
  555. DDDDDDDDDDDDDDDD     D:      - " -      29
  556. EEEEEEEEEEEEEEEE     E:      - " -      30
  557. FFFFFFFFFFFFFFFF     F:      - " -      31
  558.  
  559. The four Bitplanes should be like this:
  560.  
  561. Bitplane:  THREE              TWO              ONE             ZERO
  562. -------------------------------------------------------------------
  563. 0000000000000000 0000000000000000 0000000000000000 0000000000000000
  564. 0000000000000000 0000000000000000 0000000000000000 1111111111111111
  565. 0000000000000000 0000000000000000 1111111111111111 0000000000000000
  566. 0000000000000000 0000000000000000 1111111111111111 1111111111111111
  567. 0000000000000000 1111111111111111 0000000000000000 0000000000000000
  568. 0000000000000000 1111111111111111 0000000000000000 1111111111111111
  569. 0000000000000000 1111111111111111 1111111111111111 0000000000000000
  570. 0000000000000000 1111111111111111 1111111111111111 1111111111111111
  571. 1111111111111111 0000000000000000 0000000000000000 0000000000000000
  572. 1111111111111111 0000000000000000 0000000000000000 1111111111111111
  573. 1111111111111111 0000000000000000 1111111111111111 0000000000000000
  574. 1111111111111111 0000000000000000 1111111111111111 1111111111111111
  575. 1111111111111111 1111111111111111 0000000000000000 0000000000000000
  576. 1111111111111111 1111111111111111 0000000000000000 1111111111111111
  577. 1111111111111111 1111111111111111 1111111111111111 0000000000000000
  578. 1111111111111111 1111111111111111 1111111111111111 1111111111111111
  579.  
  580. Translated into hexadecimal it would be:
  581.  
  582.  3    2    1    0
  583. -------------------
  584. 0000 0000 0000 0000
  585. 0000 0000 0000 FFFF
  586. 0000 0000 FFFF 0000
  587. 0000 0000 FFFF FFFF
  588. 0000 FFFF 0000 0000
  589. 0000 FFFF 0000 FFFF
  590. 0000 FFFF FFFF 0000
  591. 0000 FFFF FFFF FFFF
  592. FFFF 0000 0000 0000
  593. FFFF 0000 0000 FFFF
  594. FFFF 0000 FFFF 0000
  595. FFFF 0000 FFFF FFFF
  596. FFFF FFFF 0000 0000
  597. FFFF FFFF 0000 FFFF
  598. FFFF FFFF FFFF 0000
  599. FFFF FFFF FFFF FFFF
  600.  
  601. Now we only need to put this into the two sprite data. Remember
  602. that the Bottom Sprite (0, 2, 4 or 6) contributes with Bitplanes
  603. zero and one, while the Top Sprites (1, 3, 5 or 7) contributes
  604. with Bitplanes two and three:
  605.  
  606. /* Sprite Data for the Bottom Sprite: */
  607. UWORD chip bottom_sprite_data[36]=
  608. {
  609.   0x0000, 0x0000,
  610.  
  611.   /* Bitplane */
  612.   /* ZERO ONE */
  613.   
  614.   0x0000, 0x0000,
  615.   0xFFFF, 0x0000,
  616.   0x0000, 0xFFFF,
  617.   0xFFFF, 0xFFFF,
  618.  
  619.   0x0000, 0x0000,
  620.   0xFFFF, 0x0000,
  621.   0x0000, 0xFFFF,
  622.   0xFFFF, 0xFFFF,
  623.  
  624.   0x0000, 0x0000,
  625.   0xFFFF, 0x0000,
  626.   0x0000, 0xFFFF,
  627.   0xFFFF, 0xFFFF,
  628.  
  629.   0x0000, 0x0000,
  630.   0xFFFF, 0x0000,
  631.   0x0000, 0xFFFF,
  632.   0xFFFF, 0xFFFF,
  633.     
  634.   0x0000, 0x0000
  635. };
  636.  
  637. /* Sprite Data for the Top Sprite: */
  638. UWORD chip top_sprite_data[36]=
  639. {
  640.   0x0000, 0x0000,
  641.  
  642.   /*  Bitplane  */
  643.   /* TWO  THREE */
  644.   0x0000, 0x0000,
  645.   0x0000, 0x0000,
  646.   0x0000, 0x0000,
  647.   0x0000, 0x0000,
  648.  
  649.   0xFFFF, 0x0000,
  650.   0xFFFF, 0x0000,
  651.   0xFFFF, 0x0000,
  652.   0xFFFF, 0x0000,
  653.  
  654.   0x0000, 0xFFFF,
  655.   0x0000, 0xFFFF,
  656.   0x0000, 0xFFFF,
  657.   0x0000, 0xFFFF,
  658.  
  659.   0xFFFF, 0xFFFF,
  660.   0xFFFF, 0xFFFF,
  661.   0xFFFF, 0xFFFF,
  662.   0xFFFF, 0xFFFF,
  663.     
  664.   0x0000, 0x0000
  665. };
  666.  
  667.  
  668.  
  669. 3.5.2.2  ATTACH SPRITES
  670.  
  671. To connect two sprites you simply set the SPRITE_ATTACHED
  672. flag in the second word of the sprite data of the Top Sprite.
  673. So if you want to connect sprite 3 with sprite 2, you should
  674. set the SPRITE_ATTACHED flag in sprite 3's sprite data.
  675.  
  676. top_sprite_data[ 1 ] = SPRITE_ATTACHED;
  677.  
  678. or
  679.  
  680. UWORD chip top_sprite_data[36]=
  681. {
  682.   0x0000, SPRITE_ATTACHED,
  683.   and so on...
  684.  
  685.  
  686.  
  687. 3.5.2.3  MOVE ATTACHED SPRITES
  688.  
  689. Once two sprites are attached you simply reserve them, and you
  690. have got one 15 coloured sprite:
  691.  
  692.   /* Reserve sprite 2 as Bottom Sprite: */
  693.   bottom_sprite_got = GetSprite( &my_bottom_sprite, 2 );
  694.  
  695.   if( bottom_sprite_got != 2 )
  696.     /* ERROR! */
  697.  
  698.  
  699.   /* Reserve sprite 3 as Top Sprite: */
  700.   top_sprite_got = GetSprite( &my_top_sprite, 3 );
  701.  
  702.   if( top_sprite_got != 3 )
  703.     /* ERROR! */
  704.  
  705. It is important that both of the sprites are moved
  706. simultaneously so the Attach function will work. The nice thing
  707. is that if you move the Bottom sprite, the Top sprite will also
  708. move automatically. If you on the other hand move the Top
  709. sprite only, the Bottom sprite will remain unchanged, and the
  710. special Attach function will no work. (Back to 3 colours.)
  711.  
  712. If you want to have some fun you can reserve sprite 1 and set
  713. the SPRITE_ATTACHED flag. Since sprite 0 is already used by
  714. Intuition as the pointer, sprite 1 would be attached to the
  715. pointer, and you could have a 15 coloured pointer! (Whenever
  716. Intuition moves the pointer (sprite 0, which is the Bottom
  717. sprite), your sprite (sprite 1, Top Sprite) will move
  718. automatically.) (You can change Intuition's pointer by calling
  719. the function SetPointer. See chapter 2 WINDOWS for more
  720. information.)
  721.  
  722.  
  723.  
  724. 3.5.3  LEVELS
  725.  
  726. Each sprite has its own "level" (priority) which means that
  727. some sprites will move over, and some under other sprites when
  728. they touch each other. The higher sprite number the lower level
  729. (priority). That means that sprite 3 will move over sprite 4,
  730. while sprite 2 will move over sprite 3:
  731.  
  732.    --------
  733.    | 7    |
  734.    |   --------
  735.    ----| 6    |
  736.        |   --------
  737.        ----| 5    |
  738.            |   --------
  739.            ----| 4    |
  740.                |   --------
  741.                ----| 3    |
  742.                    |   --------
  743.                    ----| 2    |
  744.                        |   --------
  745.                        ----| 1    |
  746.                            |   --------
  747.                            ----| 0    |
  748.                                |      |
  749.                                --------
  750.  
  751. This can be used in many ways. For example, if you are writing
  752. a game with a small man jumping into a box, you can use two
  753. sprites. One for the man, and one for the box. The important
  754. thing to remember is that the box must have a lower sprite
  755. number than the man. If you then would place the man at the
  756. same position as the box, the man would appear to go inside
  757. the box:
  758.  
  759.      O
  760.    -----
  761.      |
  762.      ^         #######
  763.     / \        #######
  764.     Man          Box  
  765.   (Sprite 2)  (Sprite 1)
  766.  
  767.      O
  768.    -----
  769.      |
  770.   #######
  771.   #######
  772.   Man (Sprite 2)
  773.   Box (Sprite 1)
  774.  
  775.  
  776.  
  777. 3.6  FUNCTIONS
  778.  
  779. GetSprite()
  780.  
  781.   This function reserves a sprite. You must always reserve a
  782.   sprite before you may use it.
  783.   
  784.   Synopsis:   spr_got = GetSprite( my_sprite, spr_wanted );
  785.  
  786.   spr_got:    (long) GetSprite() returns the number of the
  787.               sprite you got (0-7). If it could not get the
  788.               desired sprite, it returns -1. Remember to check
  789.               if you got the sprite you wanted! (the 
  790.               SimpleSprite structure's num field will also
  791.               be initialized automatically.)
  792.  
  793.   my_sprite:  (struct SimpleSprite *) Pointer to your
  794.               SimpleSprite structure.
  795.  
  796.   spr_wanted: (long) The number of the hardware sprite you want
  797.               to use (0-7). If it does not matter which sprite
  798.               you get you can write -1. (The System will then
  799.               give you any free hardware sprite)
  800.  
  801. MoveSprite()
  802.  
  803.   Use this function to move a sprite.
  804.  
  805.   Synopsis:  MoveSprite( view_port, my_sprite, x, y );
  806.  
  807.   view_port: (struct ViewPort *) Pointer to the ViewPort which
  808.              this sprite is connected to, or 0 if the sprite
  809.              is connected to the current View.
  810.  
  811.   my_sprite: (struct SimpleSprite *) Pointer to your
  812.              SimpleSprite structure.
  813.  
  814.   x, y:      (long) The new position on the display. (Sprites
  815.              use low-resolution pixels.)
  816.  
  817.  
  818. ChangeSprite()
  819.  
  820.   This function changes the sprite data (image) of a sprite.
  821.  
  822.   Synopsis:  ChangeSprite( view_port, my_sprite, new_data );
  823.  
  824.   view_port: (struct ViewPort *) Pointer to the ViewPort which
  825.              this sprite is connected to, or 0 if the sprite is
  826.              connected to the current View.
  827.  
  828.   my_sprite: (struct SimpleSprite *) Pointer to your
  829.              SimpleSprite structure.
  830.  
  831.   new_data:  (short *) Pointer to the new sprite data.
  832.  
  833.   
  834. FreeSprite()
  835.  
  836.   This function returns an already reserved sprite.
  837.  
  838.   Synopsis:   FreeSprite( sprite_got );
  839.  
  840.   sprite_got: (long) The sprite you want to free (0-7).
  841.  
  842.  
  843. WaitTOF()
  844.  
  845.   This function waits for the video beam to reach the top of
  846.   the display. Can be used if you want to slow down the speed
  847.   a bit, and make the animation smoother.
  848.   
  849.   Synopsis: WaitTOF();
  850.  
  851.  
  852.  
  853. 3.7  EXAMPLES
  854.  
  855. Example1
  856.   This program shows how to declare and initialize some sprite
  857.   data and a SimpleSprite structure. It also shows how to
  858.   reserve a sprite (sprite 2), and how to move it around. The
  859.   user moves the sprite by pressing the arrow keys.
  860.  
  861. Example2
  862.   This program shows how to declare and initialize some sprite
  863.   data and a SimpleSprite structure. It also shows how to
  864.   reserve a sprite (sprite 2), and how to move it around. The
  865.   user moves the sprite by pressing the arrow keys. In this
  866.   example we animate the sprite (6 frames, taken from
  867.   the arcade game Miniblast).
  868.  
  869. Example3
  870.   This program shows how to set up a 15 coloured sprite, and
  871.   how to move it around.