home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / datafiles / text / c_manual / amiga / appendices / functionsandlibraries / graphicslibrary.doc < prev    next >
Text File  |  1995-02-27  |  38KB  |  1,370 lines
  1. 2    GRAPHICS LIBRARY
  2.  
  3. 2.1  OPEN THE GRAPHICS LIBRARY
  4.  
  5. The Graphics Library must have been opened before you may use
  6. the functions listed in this file.
  7.  
  8.  
  9.   /* Declare a pointer to the Graphics Library: */
  10.   struct GfxBase *GfxBase;
  11.  
  12.   /* Open the Graphics Library: */
  13.   GfxBase = (struct GfxBase *)
  14.     OpenLibrary( "graphics.library", 0 );
  15.   
  16.   if( !GfxBase )
  17.     exit(); /* Could NOT open the Graphics Library! */
  18.  
  19.  
  20.   /* ... */
  21.  
  22.  
  23.   /* Close the Graphics Library: */
  24.   CloseLibrary( GfxBase );
  25.  
  26.  
  27.  
  28. 2.2  FUNCTIONS
  29.  
  30. AddBob()
  31.  
  32.   This function will add a BOB to the current list of graphical
  33.   objects. Remember to remove all BOBs from the list before
  34.   your program terminates. Either use the RemBob() or RemIBob()
  35.   functions to remove a BOB.
  36.  
  37.   Synopsis:  AddBob( bob, rast_port );
  38.  
  39.   bob:       (struct Bob *) Pointer to an already initialized
  40.              Bob structure. The Bob structure must also have
  41.              been connected to an initialized VSprite
  42.              structure.
  43.  
  44.   rast_port: (struct RastPort *) Pointer to the display's
  45.              RastPort. The display must have been opened before
  46.              you may add BOBs to it. NOTE! Before you may call
  47.              this function you must have declared and
  48.              initialized a GelsInfo structure, and linked it
  49.              to this RastPort.
  50.  
  51.  
  52.  
  53. AddVSprite()
  54.  
  55.   This function will add a VSprite to the VSprite list.
  56.  
  57.   Synopsis: AddVSprite( vsprite, rp );
  58.  
  59.   vsprite:  (struct VSprite *) Pointer to an initialized
  60.             VSprite structure.
  61.  
  62.   rp:       (struct RastPort *) Pointer to the RastPort.
  63.  
  64.  
  65.  
  66. AllocRaster()
  67.  
  68.   This function reserves display memory (one BitPlane).
  69.  
  70.   Synopsis: pointer = AllocRaster( width, height );
  71.  
  72.   pointer   (PLANEPTR) Pointer to the allocated memory or NULL
  73.             if enough memory could not be reserved.
  74.  
  75.   width:    (long) The width of the BitMap.
  76.  
  77.   height:   (long) The height of the BitMap.
  78.  
  79.  
  80.  
  81. AreaDraw()
  82.  
  83.   This function will add a new vertex to the vector list. 
  84.  
  85.   Synopsis:  AreaDraw( rast_port, x, y );
  86.  
  87.   rast_port: (struct RastPort *) Pointer to the RastPort that
  88.              should be affected.
  89.  
  90.   x:         (long) New X position.
  91.  
  92.   y:         (long) New Y position.
  93.  
  94.  
  95.  
  96. AreaEllipse()
  97.  
  98.   This function will draw a filled ellipse. Remember to
  99.   allocate a temporary buffer of at least the same size as the
  100.   largest object that will be drawn.
  101.  
  102.   Synopsis:  AreaEllipse( rast_port, x, y, width, height );
  103.  
  104.   rast_port: (struct RastPort *) Pointer to the RastPort in
  105.              which the filled ellipse should be drawn.
  106.  
  107.   x:         (long) X position of the filled ellipse.
  108.  
  109.   y:         (long) Y position of the filled ellipse.
  110.  
  111.   width:     (long) The width of the left or right part of
  112.              the ellipse.
  113.  
  114.   height:    (long) The height of the top or bottom part of
  115.              the ellipse.
  116.  
  117.  
  118.  
  119. AreaEnd()
  120.  
  121.   This function will close, draw and fill the polygon.
  122.  
  123.   Synopsis:  AreaEnd( rast_port );
  124.  
  125.   rast_port: (struct RastPort *) Pointer to the RastPort that
  126.              should be affected.
  127.  
  128.  
  129.  
  130. AreaMove()
  131.  
  132.   This function will start a new polygon.
  133.  
  134.   Synopsis:  AreaMove( rast_port, x, y );
  135.  
  136.   rast_port: (struct RastPort *) Pointer to the RastPort that
  137.              should be affected.
  138.  
  139.   x:         (long) Start X position.
  140.  
  141.   y:         (long) Start Y position.
  142.  
  143.  
  144.  
  145. AskSoftStyle()
  146.  
  147.   This function tells us how a specified font may be changed,
  148.   and which styles may be automatically created. Use the
  149.   function SetSoftStyle() to later change style. The reason why
  150.   you have to check if you are allowed to alter the style is
  151.   that some fonts may look very bad when altered.
  152.   
  153.   Note that you should always first try to load the font with
  154.   the desired style. It is only when the desired style does not
  155.   exist you should try to modify it with the SetSoftStyle()
  156.   function.
  157.  
  158.   Synopsis:  a_style = AskSoftStyle( rast_port )
  159.  
  160.   a_style:   (UWORD) The function returns a bit field where the
  161.              allowed style bits for the checked font are set. This
  162.              value should be used as a parameter when you later
  163.              call the SetSoftStyle() function.
  164.  
  165.   rast_port: (struct RastPort *) Pointer to the rastport to
  166.              which the font you want to check is connected.
  167.  
  168.  
  169.  
  170. AvailFonts()
  171.  
  172.   This function will scan through the font directory of the
  173.   system disk, and return a complete list of available fonts.
  174.  
  175.   Synopsis: missing = AvailFonts( buffer, size, type );
  176.  
  177.   missing:  (long) If the buffer was not big enough to store
  178.             the complete list of fonts in the extra number of
  179.             bytes needed is returned. If 0 is returned the
  180.             buffer was big enough for a complete list of fonts.
  181.  
  182.   buffer:   (char *) Pointer to some memory were the list of
  183.             fonts can be stored.
  184.           
  185.   size:     (long) The size of the buffer (in bytes).
  186.  
  187.   type:     (long) If you want to look for available fonts
  188.             which are already in the memory set the flag
  189.             "AFF_MEMORY". If you want to search the disk for
  190.             available fonts, set the flag "AFF_DISK". To
  191.             search both the memory and the disk set both flags
  192.             with the binary OR operator between:
  193.             "AFF_DISK | AFF_MEMORY".
  194.  
  195.  
  196.  
  197. BltBitMap()
  198.  
  199.   This function copies parts of BitMaps directly without
  200.   worrying about overlapping layers.
  201.  
  202.   Synopsis: BltBitMap( sb, sx, sy, db, dx, dy, w, h, fl, m, t );
  203.  
  204.   sb:       (struct BitMap *) Pointer to the "source" BitMap.
  205.  
  206.   sx:       (long) X offset, source.
  207.  
  208.   sy:       (long) Y offset, source.
  209.  
  210.   db:       (struct BitMap *) Pointer to the "destination"
  211.             BitMap.
  212.  
  213.   dx:       (long) X offset, destination.
  214.  
  215.   dy:       (long) Y offset, destination.
  216.  
  217.   w:        (long) The width of the memory area that should be
  218.             copied.
  219.  
  220.   h:        (long) The height of the memory area that should be
  221.             copied.
  222.  
  223.   fl:       (long) The four leftmost bits tells the blitter
  224.             what kind of logically operations should be done.
  225.  
  226.   m:        (long) You can here define a BitMap mask, and tell
  227.             the blitter which BitPlanes should be used, and
  228.             which should not. The first bit represents the
  229.             first BitPlane, the second bit the second BitPlane
  230.             and so on. If the bit is on (1) the corresponding
  231.             BitPlane will be used, else (0) the BitPlane will
  232.             not be used. To turn off BitPlane zero and two, set
  233.             the mask value to 0xFA (11111010). To use all
  234.             BitPlanes set the mask value to 0xFF (11111111).
  235.  
  236.   t:        (char *) If the copy overlaps and this pointer
  237.             points to some chip-memory, the memory will be used
  238.             to store the temporary area in. However, normally
  239.             you do not need to bother about this value.
  240.  
  241.  
  242.  
  243. BltClear()
  244.  
  245.   This function clears large rectangular memory areas. This
  246.   function work together with the blitter and is therefore very
  247.   fast.
  248.  
  249.   Synopsis: BltClear( pointer, bytes, flags );
  250.  
  251.   pointer   (char *) Pointer to the memory.
  252.  
  253.   bytes:    (long) The lower 16 bits tells the blitter how many
  254.             bytes per row, and the upper 16 bits how many rows.
  255.             This value is automatically calculated for you with
  256.             help of the macro RASSIZE(). Just give RASSIZE()
  257.             the correct width and height and it will return the
  258.             correct value. [RASSIZE() is defined in file
  259.             "gfx.h".]
  260.  
  261.   flags:    (long) Set bit 0 to force the function to wait
  262.             until the Blitter has finished with your request.
  263.  
  264.  
  265.  
  266. ChangeSprite()
  267.  
  268.   This function changes the sprite data (image) of a sprite.
  269.  
  270.   Synopsis:  ChangeSprite( view_port, my_sprite, new_data );
  271.  
  272.   view_port: (struct ViewPort *) Pointer to the ViewPort which
  273.              this sprite is connected to, or 0 if the sprite is
  274.              connected to the current View.
  275.  
  276.   my_sprite: (struct SimpleSprite *) Pointer to your
  277.              SimpleSprite structure.
  278.  
  279.   new_data:  (short *) Pointer to the new sprite data.
  280.   
  281.  
  282.  
  283. ClearEOL()
  284.  
  285.   This function will clear the area to the right of the current
  286.   position. The height of the area which is cleared is set to
  287.   fit the current font height.
  288.   
  289.   Synopsis: ClewarEOL( rp );
  290.  
  291.   rp:       (struct RastPort *) Pointer to a rastport. The area
  292.             from the current position to the right edge of the
  293.             rastport is cleared. The height of the area
  294.             depends on the current font size. Normally is the
  295.             cleared area set to colour 0, but if you are using
  296.             draw mode "JAM2" will the area be filled with the
  297.             BgPen colour.
  298.  
  299.  
  300. ClearScreen()
  301.  
  302.   This function will clear the area to the right of the current
  303.   position and the area below.
  304.  
  305.   Synopsis: ClewarScreen( rp );
  306.  
  307.   rp:       (struct RastPort *) Pointer to a rastport. The area
  308.             from the current position to the right edge of the
  309.             rastport is cleared. The area below is also cleared.
  310.             Normally is the cleared area set to colour 0, but
  311.             if you are using draw mode "JAM2" will the area be
  312.             filled with the BgPen colour.
  313.  
  314.  
  315.  
  316. ClipBlit()
  317.  
  318.   This function copies parts of BitMaps with help of Rastports
  319.   and will therefore care about overlapping layers, and should
  320.   be used if you have windows on your display.
  321.  
  322.   Synopsis: ClipBlit( srp, sx, sy, drp, dx, dy, w, h, flag );
  323.  
  324.   srp:      (struct RastPort *) Pointer to the "source"
  325.             RastPort.
  326.  
  327.   sx:       (long) X offset, source.
  328.  
  329.   sy:       (long) Y offset, source.
  330.  
  331.   drp:      (struct RastPort *) Pointer to the "destination"
  332.             RastPort.
  333.  
  334.   dx:       (long) X offset, destination.
  335.  
  336.   dy:       (long) Y offset, destination.
  337.  
  338.   w:        (long) The width of the memory area that should be
  339.             copied.
  340.  
  341.   h:        (long) The height of the memory area that should be
  342.             copied.
  343.  
  344.   flag:     (long) This value tells the blitter what kind of
  345.             logically operations should be done. See below for
  346.             more information.
  347.  
  348.  
  349.  
  350. CloseFont()
  351.  
  352.   All fonts you have opened with the OpenFont() function must
  353.   be "closed" before your program terminates! You close ROM
  354.   fonts by calling the CloseFont() function.
  355.  
  356.   Synopsis: CloseFont( font );
  357.  
  358.   font:     (struct TextFont *) Pointer to a previously opened
  359.             TextFont structure. Note that you should NOT try to
  360.             close a font which you have not opened!
  361.  
  362.  
  363.  
  364. DoCollision()
  365.  
  366.   This function tells the system to check all objects, and
  367.   call the collision routines if any object has hit one or
  368.   more borders or another object.
  369.  
  370.   Note! Whenever you want to check for collision you should
  371.   first sort the list by calling the SortGList() function.
  372.   The system may otherwise miss some objects.
  373.  
  374.   Synopsis:  DoCollision( rast_port );
  375.   
  376.   rast_port: (struct RastPort *) Pointer to the RastPort to
  377.              which the objects you want to check are connected
  378.              to.
  379.  
  380.  
  381.  
  382. Draw()
  383.  
  384.   This function draws single lines from the current position
  385.   to the new specified position.
  386.  
  387.   Synopsis:  Draw( rast_port, x, y );
  388.  
  389.   rast_port: (struct RastPort *) Pointer to the RastPort that
  390.              should be affected.
  391.  
  392.   x:         (long) The new X position. 
  393.  
  394.   y:         (long) The new Y position.
  395.  
  396.  
  397.  
  398. DrawEllipse()
  399.  
  400.   This function will draw an ellipse.
  401.  
  402.   Synopsis:  DrawEllipse( rast_port, x, y, width, height );
  403.  
  404.   rast_port: (struct RastPort *) Pointer to the RastPort in
  405.              which the ellipse should be drawn.
  406.  
  407.   x:         (long) X position of the ellipse.
  408.  
  409.   y:         (long) Y position of the ellipse.
  410.  
  411.   width:     (long) The width of the left or right part of
  412.              the ellipse.
  413.  
  414.   height:    (long) The height of the top or bottom part of
  415.              the ellipse.
  416.  
  417.  
  418.  
  419. DrawGList()
  420.  
  421.   This function will draw the VSprites into the specified
  422.   Rastport.
  423.  
  424.   Synopsis: DrawGList( rp, vp );
  425.  
  426.   rp:       (struct RastPort *) Pointer to the RastPort.
  427.  
  428.   vp:       (struct ViewPort *) Pointer to the ViewPort.
  429.  
  430.  
  431.  
  432. Flood()
  433.  
  434.   This function will flood fill complicated objects.
  435.  
  436.   Synopsis:  Flood( rast_port, mode, x, y ); 
  437.  
  438.   rast_port: (struct RastPort *) Pointer to the RastPort that
  439.              should be affected.
  440.  
  441.   mode:      (long) Which mode should be used. If you want to
  442.              use the Colour mode set the mode variable to 1, to
  443.              get the Outline mode set the mode variable to 0.
  444.  
  445.   x:         (long) X position where the flood fill should
  446.              start.
  447.  
  448.   y:         (long) Y position where the flood fill should
  449.              start.
  450.  
  451.  
  452.  
  453. FreeColorMap()
  454.  
  455.   This function deallocates the memory that was allocated by
  456.   the GetColorMap() function. Remember to deallocate all memory
  457.   that you allocate. For every GetColorMap() function there
  458.   should be one FreeColorMap() function.
  459.  
  460.   FreeColorMap( colormap );
  461.  
  462.   colormap: (struct ColorMap *) Pointer to a ColorMap structure
  463.             that GetColorMap() returned and you now want to
  464.             deallocate.
  465.  
  466.  
  467.  
  468. FreeCprList()
  469.  
  470.   This function will return all memory that was automatically
  471.   allocated by the MrgCop() function.
  472.  
  473.   Synopsis: FreeCprList( cprlist );
  474.  
  475.   cprlist:  (struct cprlist *) Pointer to the View's cprlist
  476.             (LOFCprList) structure. If the View was interlaced
  477.             you must also call the FreeCprList function with a
  478.             pointer to the SHFCprList.
  479.  
  480.  
  481.  
  482. FreeRaster()
  483.  
  484.   This function will deallocate display memory (BitPlane).
  485.   Remember to deallocate all BitPlanes!
  486.  
  487.   Synopsis: FreeRaster( bitplane, width, height );
  488.  
  489.   bitplane: (PLANEPTR) Pointer to a Bitplane.
  490.  
  491.   width:    (long) The Bitplane's width.
  492.  
  493.   height:   (long) The Bitplane's height.
  494.  
  495.  
  496.  
  497. FreeSprite()
  498.  
  499.   This function returns an already reserved sprite.
  500.  
  501.   Synopsis:   FreeSprite( sprite_got );
  502.  
  503.   sprite_got: (long) The sprite you want to free (0-7).
  504.  
  505.  
  506.  
  507. FreeVPortCopLists()
  508.  
  509.   This function will return all memory that was automatically
  510.   allocated by the MakeVPort() function. Remember to call
  511.   FreeVPortCopLists() for every ViewPort you have created!
  512.  
  513.   Synopsis: FreeVPortCopLists( viewport );
  514.  
  515.   view:     (struct ViewPort *) Pointer to the ViewPort.
  516.  
  517.  
  518.  
  519. GetColorMap()
  520.  
  521.   This function allocates and initializes a ColorMap structure.
  522.  
  523.   Synopsis: colormap = GetColorMap( colours );
  524.  
  525.   colormap: (struct ColorMap *) GetColorMap returns a pointer
  526.             to the ColorMap structure it has allocated and
  527.             initialized, or NULL if not enough memory.
  528.  
  529.   colours:  (long) A value specifying how many colours you
  530.             want that the ColorMap structure should store.
  531.             (1, 2, 4, 8, 16, 32)
  532.  
  533.  
  534.  
  535. GetSprite()
  536.  
  537.   This function reserves a sprite. You must always reserve a
  538.   sprite before you may use it.
  539.   
  540.   Synopsis:   spr_got = GetSprite( my_sprite, spr_wanted );
  541.  
  542.   spr_got:    (long) GetSprite() returns the number of the
  543.               sprite you got (0-7). If it could not get the
  544.               desired sprite, it returns -1. Remember to check
  545.               if you got the sprite you wanted! (the 
  546.               SimpleSprite structure's num field will also
  547.               be initialized automatically.)
  548.  
  549.   my_sprite:  (struct SimpleSprite *) Pointer to your
  550.               SimpleSprite structure.
  551.  
  552.   spr_wanted: (long) The number of the hardware sprite you want
  553.               to use (0-7). If it does not matter which sprite
  554.               you get you can write -1. (The System will then
  555.               give you any free hardware sprite.)
  556.  
  557.  
  558.  
  559. InitBitMap()
  560.  
  561.   This function initializes a BitMap structure.
  562.  
  563.   Synopsis: InitBitMap( bitmap, depth, width, height );
  564.  
  565.   bitmap: (struct BitMap *) Pointer to the BitMap.
  566.  
  567.   depth:  (long) How many BitPlanes used.
  568.  
  569.   width:  (long) The width of the raster.
  570.  
  571.   height: (long) The height of the raster.
  572.  
  573.  
  574.  
  575. InitGels()
  576.  
  577.   This function "gives" an already prepared GelsInfo structure
  578.   to the system.
  579.  
  580.   Synopsis: InitGels( head, tail, ginfo );
  581.  
  582.   head:     (struct VSprite *) Pointer to the first "dummy"
  583.             VSprite structure.
  584.  
  585.   tail:     (struct VSprite *) Pointer to the second "dummy"
  586.             VSprite structure.
  587.  
  588.   ginfo:    (struct GelsInfo *) Pointer to an initialized GelsInfo
  589.             structure.
  590.  
  591.  
  592.  
  593. InitMasks()
  594.  
  595.   This function will automatically create a collision and a
  596.   border line mask for a VSprite or BOB.
  597.  
  598.   Synopsis: InitMasks( vsprite );
  599.   
  600.   vsprite:  (struct VSprite *) Pointer to the object's VSprite
  601.             structure. InitMasks() will work both with simple
  602.             VSprites as well as with BOBs. It will look at the
  603.             objects image and do a binary OR operation on it,
  604.             and stores the result in the memory area which 
  605.             "CollMask" is pointing to.
  606.             
  607.             If you have created a collision mask for a BOB can
  608.             you also use it as the BOB's shadow image.
  609.             
  610.             The function will also create a "border line" which
  611.             is used for boundary collisions.
  612.  
  613.  
  614.  
  615. InitRastPort()
  616.  
  617.   This function initializes a RastPort.
  618.  
  619.   Synopsis:  InitRastPort( rast_port );
  620.  
  621.   rast_port: (RastPort *) Pointer to the RastPort that should
  622.              be Initialized.
  623.  
  624.  
  625.  
  626. InitView()
  627.  
  628.   This function will initialize a View structure.
  629.  
  630.   Synopsis: InitView( view );
  631.   
  632.   view:     (struct View *) Pointer to the View that should be
  633.             initialized.
  634.  
  635.  
  636.  
  637. InitVPort()
  638.  
  639.   This function will initialize a ViewPort structure.
  640.  
  641.   Synopsis:  InitVPort( view_port );
  642.   
  643.   view_port: (struct ViewPort *) Pointer to the ViewPort that
  644.              should be initialized.
  645.  
  646.  
  647.  
  648. MakeVPort()
  649.  
  650.   This function prepares the Amiga's hardware (especially the
  651.   Copper) to display a ViewPort. NOTE! You have to prepare
  652.   EVERY ViewPort you are going to use!
  653.  
  654.   Synopsis: MakeVPort( view, viewport ); 
  655.  
  656.   view:     (struct View *) Pointer to the ViewPort's View.
  657.  
  658.   viewport: (struct ViewPort *) Pointer to the ViewPort.
  659.  
  660.  
  661.  
  662. Move()
  663.  
  664.   This function moves the cursor.
  665.  
  666.   Synopsis:  Move( rast_port, x, y );
  667.  
  668.   rast_port: (struct RastPort *) Pointer to the RastPort that
  669.              should be affected.
  670.  
  671.   x:         (long) The new X position. 
  672.  
  673.   y:         (long) The new Y position.
  674.  
  675.  
  676.  
  677. MoveSprite()
  678.  
  679.   Use this function to move a sprite.
  680.  
  681.   Synopsis:  MoveSprite( view_port, my_sprite, x, y );
  682.  
  683.   view_port: (struct ViewPort *) Pointer to the ViewPort which
  684.              this sprite is connected to, or 0 if the sprite
  685.              is connected to the current View.
  686.  
  687.   my_sprite: (struct SimpleSprite *) Pointer to your
  688.              SimpleSprite structure.
  689.  
  690.   x, y:      (long) The new position on the display. (Sprites
  691.              use low-resolution pixels.)
  692.  
  693.  
  694.  
  695. MrgCop()
  696.  
  697.   This function puts together all displayinstructions and
  698.   prepares the view to be showed.
  699.  
  700.   Synopsis: MrgCop( view );
  701.  
  702.   view:     (struct View *) Pointer to the View.
  703.  
  704.  
  705.  
  706. LoadView()
  707.  
  708.   This function will start showing a View. Remember that when
  709.   you close your View you must switch back to the old view.
  710.   (See examples for more details.)
  711.  
  712.   Synopsis: LoadView( view );
  713.  
  714.   view:     (struct View *) Pointer to the View.
  715.  
  716.  
  717.  
  718. OpenFont()
  719.  
  720.   This function is used to get access to a ROM font. You
  721.   initialize a TextAttr structure with your requirements,
  722.   and send a pointer to it as the only parameter. If
  723.   OpenFont() finds the font it returns a pointer to a
  724.   TextFont structure and tells the system that you are using
  725.   the font. Remember to close all fonts you have opened with
  726.   the CloseFont() function.
  727.  
  728.   Synopsis: font = OpenFont( attr );
  729.  
  730.   font:     (struct TextFont *) Pointer to a TextFont structure
  731.             or NULL if OpenFont() could not find the font.
  732.  
  733.   attr:     (struct TextAttr *) Pointer to an initialized
  734.             TextAttr structure. OpenFont() will try to open the
  735.             font which closes matches your requirements.
  736.  
  737.  
  738.  
  739. PolyDraw()
  740.  
  741.   This function will draw multiple lines.
  742.  
  743.   Synopsis:    PolyDraw( rast_port, number, coordinates );
  744.  
  745.   rast_port:   (struct RastPort *) Pointer to the RastPort that
  746.                should be affected.
  747.  
  748.   number:      (long) The number of coordinates (x,y) defined
  749.                in the array.
  750.  
  751.   coordinates: (short *) Pointer to an array of coordinates.
  752.  
  753.  
  754.  
  755. ReadPixel()
  756.  
  757.   This function reads the colour value of a pixel.
  758.  
  759.   Synopsis:  colour = ReadPixel( rast_port, x, y );
  760.  
  761.   colour:    (long) ReadPixel returns the colour value of the
  762.              specified pixel (colour 0 - 255 ) or -1 if the
  763.              coordinates were outside the Raster.
  764.  
  765.   rast_port: (struct RastPort *) Pointer to the RastPort which
  766.              contain the pixel you want to examine.
  767.  
  768.   x:         (long) X position of the pixel. 
  769.  
  770.   y:         (long) Y position of the pixel.
  771.  
  772.  
  773.  
  774. RectFill()
  775.  
  776.   This function will draw filled rectangles.
  777.  
  778.   Synopsis:  RectFill( rast_port, minx, miny, maxx, maxy );
  779.  
  780.   rast_port: (struct RastPort *) Pointer to the RastPort that
  781.              should be affected.
  782.  
  783.   minx:      (long) Left position of the rectangle.
  784.  
  785.   miny:      (long) Top          - " -
  786.  
  787.   maxx:      (long) Right        - " -
  788.  
  789.   maxy:      (long) Bottom       - " -
  790.  
  791.  
  792.  
  793. RemBob()
  794.  
  795.   This function will remove a specified BOB for the list of
  796.   graphical elements. The BOB will first disappear after
  797.   you have resorted and drawn the list again (using the
  798.   SortGList() and DrawGList() functions). If you want to
  799.   remove the BOB and the image immediately you should use
  800.   the RemIBob() function.
  801.  
  802.   Synopsis: RemBob( bob );
  803.   
  804.   bob:      (struct Bob *) Pointer to the BOB that should be
  805.             removed. Do not try to remove a BOB which you have
  806.             not previously added to the list.
  807.  
  808.  
  809.  
  810. RemIBob()
  811.  
  812.   This function will remove a specified BOB from the current
  813.   list of graphical elements. The image will also immediately
  814.   be removed.
  815.  
  816.   Synopsis:  RemIBob( bob, rast_port, view_port );
  817.   
  818.   bob:       (stuct Bob *) Pointer to the BOB that should
  819.              immediately be removed. The image will directly
  820.              be removed (and the background restored if the
  821.              SAVEBACK flag was set).              
  822.   
  823.   rast_port: (struct RastPort *) Pointer to the RastPort to
  824.              which the BOB is connected.
  825.   
  826.   view_port: (struct ViewPort *) Pointer to the display's
  827.              ViewPort.
  828.  
  829.  
  830.  
  831. RemVSprite()
  832.   
  833.   This function will remove a previously added VSprite.
  834.  
  835.   Synopsis: RemVSprite( vsprite );
  836.  
  837.   vsprite:  (struct VSprite *) Pointer to the VSprite you want
  838.             to remove.
  839.  
  840.  
  841.  
  842. ScrollRaster()
  843.  
  844.   This function will scroll a rectangular area of a raster.
  845.  
  846.   Synopsis:  ScrollRaster( rp, dx, dy, minx, miny, maxx, maxy );
  847.  
  848.   rp:        (struct RastPort *) Pointer to the RastPort that
  849.              should be affected.
  850.  
  851.  
  852.   dx:        (long) Delta X movement. (A positive number moves
  853.              the area to the right, a negative number to the
  854.              left.)
  855.  
  856.   dy:        (long) Delta Y movement. (A positive number moves
  857.              the area down, a negative number up.)
  858.  
  859.   minx:      (long) Left edge of the rectangle.
  860.  
  861.   miny:      (long) Top edge of the rectangle.
  862.  
  863.   maxx:      (long) Right edge of the rectangle.
  864.  
  865.   maxy:      (long) Bottom edge of the rectangle.
  866.  
  867.  
  868.  
  869. SetAPen()
  870.  
  871.   This function will change the FgPen's colour.
  872.  
  873.   Synopsis:   SetAPen( rast_port, new_colour );
  874.  
  875.   rast_port:  (struct RastPort *) Pointer to the RastPort that
  876.               should be affected.
  877.  
  878.   new_colour: (long) A new colour value.
  879.  
  880.  
  881.  
  882. SetBPen()
  883.  
  884.   This function will change the BgPen's colour.
  885.  
  886.   Synopsis:   SetBPen( rast_port, new_colour );
  887.  
  888.   rast_port:  (struct RastPort *) Pointer to the RastPort that
  889.               should be affected.
  890.  
  891.   new_colour: (long) A new colour value.
  892.  
  893.  
  894.  
  895. SetCollision()
  896.  
  897.   This function will set a collision routine function.
  898.  
  899.   Synopsis:  SetCollision( number, function, gels_info );
  900.  
  901.   number:    (long) Which routine (0 - 15) you set.
  902.  
  903.   function:  (__fgptr = (void *()) Pointer to the function
  904.              which should be executed when the specified
  905.              collision routine occurs.
  906.  
  907.   gels_info: (struct GelsInfo *) Pointer to the GelsInfo
  908.              structure. Note that you must have given the
  909.              collHandler field of the GelsInfo structure a
  910.              pointer to a collTable structure before you may
  911.              use this function!
  912.  
  913.  
  914.  
  915. SetDrMd()
  916.  
  917.   This function will change the drawing mode.
  918.  
  919.   Synopsis:  SetDrMd( rast_port, new_mode );
  920.  
  921.   rast_port: (struct RastPort *) Pointer to the RastPort that
  922.              should be affected.
  923.  
  924.   new_mode:  (long) The new drawing mode. Set one of the
  925.              following: JAM1, JAM2, COMPLEMENT, INVERSVID|JAM1
  926.              or INVERSVID|JAM2.
  927.  
  928.              JAM1           The FgPen will be used, the
  929.                             background unchanged. (One colour
  930.                             jammed into a Raster.)
  931.  
  932.              JAM2           The FgPen will be used as foreground
  933.                             pen while the background (when you
  934.                             are writing text for example) will
  935.                             be filled with the BgPen's colour.
  936.                             (Two colours are jammed into a
  937.                             Raster.)
  938.  
  939.              COMPLEMENT     Each pixel affected will be drawn
  940.                             with the binary complement colour.
  941.                             Where you write 1's the
  942.                             corresponding bit in the Raster
  943.                             will be reversed.
  944.  
  945.              INVERSVID|JAM1 This mode is only use together with
  946.                             text. Only the background of the
  947.                             text will be drawn with the FgPen.
  948.  
  949.              INVERSVID|JAM2 This mode is only use together with
  950.                             text. The background of the text
  951.                             will be drawn with the FgPen, and
  952.                             the characters itself with the
  953.                             BgPen.
  954.  
  955.  
  956.  
  957. SetFont()
  958.  
  959.   This function will change a RastPort's font. The font must
  960.   of course have been successfully opened before you may start
  961.   to use it.
  962.  
  963.   Synopsis: error = SetFont( rp, font );
  964.  
  965.   error:    (long) If OK 0 is returned, else an error number is
  966.             returned which means something went wrong.
  967.  
  968.   rp:       (struct RastPort *) Pointer to the RastPort that
  969.             should be affected.
  970.  
  971.   font:     (struct TextFont *) Pointer to a TextFont structure
  972.             which has previously been "opened".
  973.  
  974.  
  975.  
  976. SetRast()
  977.  
  978.   This function sets a whole Raster to a specific colour.
  979.  
  980.   Synopsis:  SetRast( rast_port, colour );
  981.  
  982.   rast_port: (struct RastPort *) Pointer to the RastPort that
  983.              should be affected.
  984.  
  985.   colour:    (long) The colour reg. you want to fill the whole
  986.              raster with.
  987.  
  988.  
  989.  
  990. SetRGB4()
  991.  
  992.   This function allows you to change your screen's colours.
  993.   Each colour may be picked out of a 4096 colour palette. (16
  994.   levels of red, 16 levels of green and 16 levels of blue;
  995.   16*16*16 = 4096.)
  996.  
  997.   IMPORTANT! Before you may use this function you must have
  998.   opened the Graphics Library. (All other functions are in the
  999.   Intuition Library.) (See chapter 0 AMIGA for more
  1000.   information.)
  1001.  
  1002.   Synopsis:   SetRGB4( viewport, register, red, green, blue );
  1003.            
  1004.   viewport:   (struct ViewPort *) Pointer to a ViewPort which
  1005.               colour registers we are going to change. We can
  1006.               find the screen's ViewPort in the Screen
  1007.               structure. (If my_screen is a pointer to a Screen
  1008.               structure, this will get us a pointer to that
  1009.               screen's ViewPort: &my_screen->ViewPort)
  1010.  
  1011.   register:   (long) The colour register you want to change.
  1012.               The screen's Depth decides how many colour
  1013.               registers the screen have:
  1014.  
  1015.               Depth  Colour Registers
  1016.               -----------------------
  1017.               1      0 - 1
  1018.               2      0 - 3
  1019.               3      0 - 7
  1020.               4      0 - 15
  1021.               5      0 - 31
  1022.               6      0 - 63
  1023.  
  1024.   red:        Amount of red. (0 - 15)
  1025.  
  1026.   green:      Amount of green. (0 - 15 )
  1027.  
  1028.   blue:       Amount of blue. (0 - 15 )
  1029.  
  1030.   Eg: SetRGB4( &my_screen->ViewPort, 2, 15, 15, 0 ); will
  1031.   change colour register 2 to be light yellow. (Red and green
  1032.   together will be yellow.)
  1033.  
  1034.  
  1035.  
  1036. SetSoftStyle()
  1037.  
  1038.   This function will alter the style of a specified font. You
  1039.   should first find out which styles you may alter by calling
  1040.   the AskSoftStyle() function before you call this function.
  1041.  
  1042.   Synopsis:  new_style = SetSoftStyle( rp, style, a_style );
  1043.  
  1044.   new_style: (UWORD) The function will only create the styles
  1045.              it is allowed to do (see a_styles), and it may
  1046.              therefore happen that the function will not
  1047.              generate all of the styles you wanted. This
  1048.              returned value tells us which style bits it used.
  1049.  
  1050.   rp:        (struct RastPort *) Pointer to the rastport to
  1051.              which the font you want to change is connected.
  1052.  
  1053.   style:     (UWORD) The desired style.
  1054.  
  1055.   a_style:   (UWORD) The styles you may use. This value was
  1056.              returned by AskSoftStyle(). If you want to be able
  1057.              to use all styles and do not care if some styles
  1058.              would look strange set this field to 0xFFFF (all
  1059.              styles allowed). This can result in some very ugly
  1060.              styles, and is therefore not recommended.
  1061.  
  1062.  
  1063.  
  1064. SortGList()
  1065.  
  1066.   This function will reorganize the VSprite list so that the
  1067.   further down on the display the sprites are positioned the
  1068.   later they will appear in the list.
  1069.  
  1070.   Synopsis: SortGList( rp );
  1071.  
  1072.   rp:       (struct RastPort *) Pointer to the RastPort.
  1073.  
  1074.  
  1075.  
  1076. Text()
  1077.  
  1078.   This function prints text into a Raster.
  1079.  
  1080.   Synopsis:  Text( rast_port, string, nr_of_chr );
  1081.  
  1082.   rast_port: (struct RastPort *) Pointer to the RastPort that
  1083.              should be affected.
  1084.  
  1085.   string:    (char *) Pointer to a text string that will be
  1086.              printed.
  1087.  
  1088.   nr_of_chr: (long) The number of characters that should be
  1089.              printed.
  1090.  
  1091.  
  1092.  
  1093. TextLength()
  1094.  
  1095.   This function will return the number of pixels wide the text
  1096.   string would be if printed with the rastport's current font.
  1097.  
  1098.   Synopsis: width = TextLength( rp, string, nr_chars );
  1099.   
  1100.   width:    (long) Number of pixels wide the text string would
  1101.             be if printed with the rastport's current font.
  1102.   
  1103.   rp:       (struct RastPort *) Pointer to the rastport.
  1104.   
  1105.   string:   (char *) Pointer to the string containing the text
  1106.             you want to measure.
  1107.   
  1108.   nr_chars: (long) Number of characters in the string that
  1109.             should be counted.
  1110.  
  1111.  
  1112.  
  1113. VBeamPos()
  1114.  
  1115.   This function will return the current vertical position of
  1116.   the video beam.
  1117.   
  1118.   Synopsis:  vert_line = VBeamPos();
  1119.   
  1120.   vert_line: (long) The current vertical position of the video
  1121.              beam.
  1122.  
  1123.  
  1124.  
  1125. WaitTOF()
  1126.  
  1127.   This function waits for the video beam to reach the top of
  1128.   the display. Can be used if you want to slow down the speed
  1129.   a bit, and make the animation smoother.
  1130.   
  1131.   Synopsis: WaitTOF();
  1132.  
  1133.  
  1134.  
  1135. WaitBOVP()
  1136.  
  1137.   This function waits for the video beam to reach the bottom of
  1138.   the specified view port. If you are redrawing something at
  1139.   the same time as the picture is drawn by the video beam the
  1140.   modified area will apear to "flicker". If you instead use
  1141.   this function to wait for the beam to pass the view port
  1142.   before you redraws it there is less risk that the display
  1143.   will start to "flicker".
  1144.   
  1145.   If you have to do a lot of drawing you may not manage to
  1146.   complete the redrawing before the video beam is once again
  1147.   moved over your drawings. In that case you have to use a
  1148.   "double buffered display". See chapter "Graphical Tricks"
  1149.   for more information.
  1150.   
  1151.   Synopsis:  WaitBOVP( view_port );
  1152.   
  1153.   view_port: (struct ViewPort *) This function will wait until
  1154.              the video beam has passed the view port which this
  1155.              field points to.
  1156.  
  1157.  
  1158.  
  1159. WritePixel()
  1160.  
  1161.   This function will draw a single pixel.
  1162.  
  1163.   Synopsis:  WritePixel( rast_port, x, y );
  1164.  
  1165.   rast_port: (struct RastPort *) Pointer to the RastPort that
  1166.              should be affected.
  1167.  
  1168.   x:         (long) X position of the pixel. 
  1169.  
  1170.   y:         (long) Y position of the pixel.
  1171.  
  1172.  
  1173.  
  1174. 2.3  MACROS
  1175.  
  1176. To use these macros you have to include the header file
  1177. "graphics/gfxmacros.h".
  1178.  
  1179.  
  1180. AreaCircle()
  1181.  
  1182.   This macro will draw a filled circle. Remember to allocate a
  1183.   temporary buffer of at least the same size as the largest
  1184.   object that will be drawn.
  1185.  
  1186.   Synopsis:  AreaCircle( rast_port, x, y, radius );
  1187.  
  1188.   rast_port: (struct RastPort *) Pointer to the RastPort in
  1189.              which the circle should be drawn.
  1190.  
  1191.   x:         (long) X position of the circle.
  1192.  
  1193.   y:         (long) Y position of the circle.
  1194.  
  1195.   radius:    (long) The circle's radius.
  1196.  
  1197.  
  1198.  
  1199. BNDROFF()
  1200.  
  1201.   This macro (declared in file "gfxmacro.h") will turn off the
  1202.   outline mode.
  1203.  
  1204.   Synopsis:  BNDROFF( rast_port );
  1205.  
  1206.   rast_port: Pointer to the RastPort which outlinefunction
  1207.              should be turned off.
  1208.  
  1209.  
  1210.  
  1211. CEND()
  1212.  
  1213.   This macro will put an "end" mark at the end of the user
  1214.   copper list. After you have added all desired copper commands
  1215.   you have to call this macro to tell the Copper that this is
  1216.   the end of the list.
  1217.  
  1218.   Synopsis: CEND( copper );
  1219.  
  1220.   copper:   (struct UCopList *) Pointer to the user copper list
  1221.             structure that should be "ended".
  1222.  
  1223.  
  1224.  
  1225. CINIT()
  1226.  
  1227.   This macro will initialize a user copper list. This should
  1228.   always be done before you may add any copper commands.
  1229.  
  1230.   Synopsis: CINIT( copper, nr_instr );
  1231.  
  1232.   copper:   (struct UCopList *) Pointer to the user copper list
  1233.             structure you have previously allocated. Note that
  1234.             the structure must be in chip memory.
  1235.         
  1236.   nr_instr: (long) This field can be used to specify how many
  1237.             copper instructions should be used. However, when
  1238.             we later set the copper instructions they will
  1239.             automatically allocate the memory which is needed,
  1240.             so this field is actually almost unnecessary. Set
  1241.             this field to 1. 
  1242.  
  1243.  
  1244.  
  1245. CMOVE()
  1246.  
  1247.   This macro will add a move instruction in a user coper list.
  1248.  
  1249.   Synopsis: CMOVE( copper, register, value );
  1250.  
  1251.   copper:   (struct UCopList *) Pointer to the user copper list
  1252.             structure you have previously allocated and
  1253.             initialized with the CINIT() macro.
  1254.  
  1255.   register: (long) Pointer to the hardware (system) register
  1256.             you want to change. If you want to change the
  1257.             colours you can find the colour registers in the
  1258.             array "color" in the Custom structure. To alter the
  1259.             first colour register you would write
  1260.             "custom.color[0]", to alter the second colour
  1261.             register you would write "custom.color[1]", and so
  1262.             on... There exist in total 32 colour registers,
  1263.             although the current screen does not necessarily
  1264.             use all of them. 
  1265.  
  1266.   value:    (long) This is the value that should be inserted.
  1267.             When you are using the colour registers this value
  1268.             should be specified in "RGB" form. The four left-
  1269.             most bit represents the blue colour, the next four
  1270.             bits the green colour, and finally the last four
  1271.             bits the red value.
  1272.  
  1273.  
  1274.  
  1275. CWAIT()
  1276.  
  1277.   This macro will add a wait instruction in a user coper list.
  1278.  
  1279.   Synopsis: CWAIT( copper, y, x );
  1280.  
  1281.   copper:   (struct UCopList *) Pointer to the user copper list
  1282.             structure you have previously allocated and
  1283.             initialized with the CINIT() macro.
  1284.        
  1285.        y:   (long) The Copper will wait for the video beam to
  1286.             reach this vertical position.        
  1287.      
  1288.        x:   (long) When the video beam has reach the above
  1289.             specified vertical position the Copper will
  1290.             continue to wait until the beam reaches this
  1291.             horizontal position. Normally this field is set to
  1292.             0, but does not have to be that. 
  1293.  
  1294.  
  1295.  
  1296. DrawCircle()
  1297.  
  1298.   This macro will draw a circle.
  1299.  
  1300.   Synopsis:  DrawCircle( rast_port, x, y, radius );
  1301.  
  1302.   rast_port: (struct RastPort *) Pointer to the RastPort in
  1303.              which the circle should be drawn.
  1304.  
  1305.   x:         (long) X position of the circle.
  1306.  
  1307.   y:         (long) Y position of the circle.
  1308.  
  1309.   radius:    (long) The circle's radius.
  1310.  
  1311.  
  1312.  
  1313. SetAfPt()
  1314.  
  1315.   This macro will set the area pattern:
  1316.  
  1317.   Synopsis:     SetAfPt( rast_port, area_pattern, pow2 );
  1318.  
  1319.   rast_port:    (struct RastPort *) Pointer to the RastPort
  1320.                 that should be affected.
  1321.  
  1322.   area_pattern: (UWORD) Pointer to an array of UWORDS that
  1323.                 generate the pattern. Each bit in the array
  1324.                 represents one dot.
  1325.  
  1326.   pow2:         (BYTE) The pattern must be two to the power of
  1327.                 pow2 lines tall. If the pattern is one line tall
  1328.                  pow2 should be set to 0, if the pattern is two
  1329.                 lines tall pow2 should be set to 1, if the
  1330.                 pattern is four lines tall pow2 should be set to
  1331.                 2, and so on. (If you use multicoloured patterns
  1332.                 the pow2 should be negative. A sixteen lines
  1333.                 tall multicoloured pattern should therefore have
  1334.                 the pow2 value set to -4 [2^4 = 16].)
  1335.  
  1336.  
  1337.  
  1338. SetDrPt()
  1339.  
  1340.   This macro will set the line pattern.
  1341.  
  1342.   Synopsis:     SetDrPt( rast_port, line_pattern );
  1343.  
  1344.   rast_port:    (struct RastPort *) Pointer to the RastPort
  1345.                 that should be affected.
  1346.  
  1347.   line_pattern: (UWORD) The pattern. Each bit represents one
  1348.                 dot. To generate solid lines you set the
  1349.                 pattern value to 0xFFFF [hex] (1111111111111111
  1350.                 [bin]).
  1351.  
  1352.  
  1353.  
  1354. SetOPen()
  1355.  
  1356.   This macro will change the AOlPen's colour. Note! This is not
  1357.   a function. It is actually a macro that is defined in the
  1358.   header file "gfxmacros.h". If you want to use this function
  1359.   you have to remember to include this file.
  1360.  
  1361.   Synopsis:   SetOPen( rast_port, new_colour );
  1362.  
  1363.   rast_port:  (struct RastPort *) Pointer to the RastPort that
  1364.               should be affected.
  1365.  
  1366.   new_colour: (long) A new colour value.
  1367.  
  1368.  
  1369.  
  1370.