Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/339.lha/xspecs.library_v0/xspecslibrary.doc.pp/xspecslibrary.doc

Text File | 1990-02-08 | 21KB | 812 lines

******************************************************************

This documentation covers xspecs.library version 0 by Richard Horne.
The xspecs.library is freely distributable in the public domain.
Kindly report any bugs to Richard Horne, (GENIE RHORNE, COMPUSERVE
71777-407, PLINK OCS428).  Suggestions for addition and improvement
are welcome.

*******************************************************************

XSpecsAllocateView

   NAME
   XSpecsAllocateView - Allocate XSpecsMemory and initialize
   data structures.

   SYNOPSIS
   Error = XSpecsAllocateView (View Modes)
   d0                          d0

   OFFSET -30

   FUNCTION
   This function allocates memory and initializes data
   structures for left and right bitmaps, rastports, and
   viewports.  Possible view modes are LowRes ($0), HiRes
   ($8000), or HAM ($800) with or without Sprites ($4000).
   See graphics/gfx.i.  Once this function has been called, you
   can use any of the Amiga Graphics functions to draw
   separately into the left and right XSpecs rastports. Use
   XSpecsLeftRastPort, XSpecsRightRastPort to find rastport
   addresses.  XSpecsAllocateView function is followed by
   XSpecsOn to turn on the XSpecs vertical blank interrupt and
   begin switching the XSpecs lenses.

   INPUTS
   d0 = ViewModes

   RESULT
   d0 = 0 if function is successful
   d0 = 1 if function unsuccessful due to improper View Mode
   d0 = 2 if function unsuccessful due to insufficient memory

   SEE ALSO
   XSpecsOn
   XSpecsLeftRastPort, XSpecsRightRastPort
   XSpecsLeftViewPort, XSpecsRightViewPort

   BUGS TBD


XSpecsChangeSprite

   NAME
   XSpecsChangeSprite - Assign XSpecs simple sprite to left and
   right viewport.  Change pixel definition of XSpecs simple
   sprite.

   SYNOPSIS
   Error = XSpecsChangeSprite (SpriteImage, SpriteNumber)
   d0                          a0           d0

   OFFSET -90

   FUNCTION
   This function attaches a simple sprite to the left and right
   viewports.  It can also be used to change the sprite pixel
   definition to the specified sprite image data.  The function
   must have been preceded by XSpecsGetSprite for assignment
   of a sprite number.

   INPUTS
   a0 - Address of sprite image data in chip memory
   d0 - Sprite number

   RESULT
   d0 = 0 if function successful
   d0 = 1 if sprite number not yet assigned using
        XSpecsGetSprite

   SEE ALSO
   XSpecsGetSprite  XSpecsMoveSprite

   BUGS  TBD


XSpecsDeallocateView

   NAME
   XSpecsDeallocateView - Free memory associated with XSpecs
   View.

   SYNOPSIS
   XSpecsDeallocateView()

   OFFSET -36

   FUNCTION
   This function frees memory used by XSpecs bitmaps,
   rastports, and viewports.  This function must be preceded
   by XSpecsOff to turn off the XSpecs vertical blank
   interrupt.

   SEE ALSO
   XSpecsAllocateView

   BUGS TBD


XSpecsDraw

   NAME
   XSpecsDraw - Draw a line in XSpecs three dimensional
   coordinates.

   SYNOPSIS
   Error = XSpecsDraw (x, y, z)
   d0                  d0 d1 d2

   OFFSET = -84

   FUNCTION
   This function draws lines from the current graphics pen
   position to points in XSpecs left and right rastports
   determined by the three dimensional XSpecs (x, y, z) input
   coordinates.  The switching of the XSpecs lenses gives the
   illusion of a single line in the three dimensional XSpecs
   coordinate system.  Use XSpecsMove to set the starting
   point for the line.  Lines are drawn using the current APen.
   See XSpecsLeftXY or XSpecsRightXY for a complete description
   of the XSpecs coordinate system.

   RESULT
   d0 = 0 if function successful
   d0 = 1 if attempt to draw outside screen limits

   SEE ALSO
   XSpecsPolyDraw XSpecsMove XSpecsLeftXY XSpecsRightXY
   XSpecsSetAPen

   BUGS TBD


XSpecsFreeSprite

   NAME
   XSpecsFreeSprite - Free simple sprite from XSpecs use.

   SYNOPSIS
   XSpecsFreeSprite (SpriteNumber)
                     d0

   OFFSET = -162

   FUNCTION
   This function frees a sprite previously assigned to XSpecs.

   INPUTS
   d0 = Sprite Number

   SEE ALSO
   XSpecsGetSprite XSpecsChangeSprite XSpecsMoveSprite

   BUGS  TBD


XSpecsGetSprite

   NAME
   XSpecsGetSprite - Assign a simple sprite for XSpecs use.

   SYNOPSIS
   SpriNum = XSpecsGetSprite (SimpleSpri,SpriImage, SpriNum)
   d0                         a0         a1         d0

   OFFSET = -156

   FUNCTION
   This function assigns a simple sprite for XSpecs use.
   Before calling this function, you must initialize a simple
   sprite data structure (only height variable need be entered,
   remainder of structure may be zero filled), and you must
   define a sprite image in chip memory.  You may request a
   particular sprite number in d0, or enter -1 in d0, and the
   next available sprite will be assigned.

   INPUTS
   a0 = Address of simple sprite structure
   a1 = Address of Chip Memory Sprite Image
   d0 = SpriteNumber (or -1)

   RESULT
   d0 = SpriteNumber assigned if function is successful
   d0 = -1 if function cannot assign sprite

   SEE ALSO
   XSpecsChangeSprite XSpecsMoveSprite XSpecsFreeSprite

   BUGS TBD


XSpecsLeftRastPort

   NAME
   XSpecsLeftRastPort - Find XSpecs left rastport address.

   SYNOPSIS
   LeftRastportAddress = XSpecsLeftRastPort()
   d0

   OFFSET = -114

   FUNCTION
   This function returns the address of the XSpecs left
   rastport.  This function must be preceded by
   XSpecsAllocateView.  You can use this address with any of
   the Amiga graphics functions to draw separately into the
   left rastport.  Convert XSpecs 3D coordinates to left
   rastport    coordinates using XSpecsLeftXY.  See XSpecsLeftXY
   for a complete description of the XSpecs coordinate system.

   RESULT
   d0 = Address of left rastport

   SEE ALSO
   XSpecsAllocateView XSpecsLeftXY XSpecsMove

   BUGS TBD


XSpecsLeftViewPort

   NAME
   XSpecsLeftViewPort - Find XSpecs left viewport address.

   SYNOPSIS
   LeftViewportAddress = XSpecsLeftViewPort()
   d0

   OFFSET = -126

   FUNCTION
   This function returns the address of the XSpecs left
   viewport.  This function must be preceded by
   XSpecsAllocateView.

   RESULT
   d0 = Address of left viewport

   SEE ALSO
   XSpecsAllocateView XSpecsLeftXY

   BUGS TBD


XSpecsLeftXY

   NAME
   XSpecsLeftXY - Convert XSpecs three dimensional coordinates
   to left rastport coordinates.

   SYNOPSIS
   LeftXY = XSpecsLeftXY (x, y, z)
   d0                     d0 d1 d2

   OFFSET = -102

   FUNCTION
   The XSpecs coordinate system is a three dimensional system
   with an origin (0, 0, 0 position) at the exact center of the
   Amiga monitor screen.  The x direction is positive from this
   point to the right and negative to the left.  The y
   direction is positive from this position moving down and
   negative moving up.  The z direction is positive from this
   position moving into the screen and negative moving out of
   the screen toward you.  For every point (x, y, z) in XSpecs
   coordinates there is a corresponding point projected into
   the both left and right rastports.  When each of these
   points are drawn separately into the left and right
   rastports, the switching of the XSpecs lenses from left to
   right will give the illusion of a single point at the XSpecs
   (x, y, z) position.  The scale of the XSpecs coordinate
   system depends on the ViewModes selected when setting up the
   XSpecs View (XSpecsAllocateView).  For LowRes views, the
   scale is chosen as 320 units horizontally across the face of
   the monitor.  For HiRes views, the scale is chosen as 640
   units horizontally across the face of the monitor.  This
   same scale is used both horizontally and vertically
   resulting in about 440 units vertically in HiRes and 220
   units vertically in LowRes at the face of the monitor.
      This function converts the input XSpecs (x,y,z)
   coordinates into rastport coordinates in the left rastport.
   Use this function to determine the position of points in the
   left rastport corresponding to an (x,y,z) position in the
   XSpecs coordinate system.  Rastport coordinates are measured
   from the upper left corner of the screen.  The rastport is
   either 320 or 640 pixels wide (depending on ViewMode) and
   200 lines high.

   INPUTS
   d0 = x (16 bits)
   d1 = y (16 bits)
   d2 = z (16 bits)

   RESULT
   d0 = LeftX (high 16 bits), LeftY (low 16 bits)
   d1 = -1 if point is outside screen limits

   SEE ALSO  XSpecsRightXY

   BUGS  TBD


XSpecsLoadRGB4

   NAME
   XSpecsLoadRGB4 - Load color data into XSpecs left and right
   viewports.

   SYNOPSIS
   XSpecsLoadRGB4 (ColorData, Count)
                   a0         d0

   OFFSET = -66

   FUNCTION
   This function assigns RGB colors to the XSpecs left and
   right viewports.  This function must have been preceded by
   XSpecsAllocateView.

   INPUTS
   a0 = Address of table of 16 bit color values
   d0 = Count, number of color values to load

   SEE ALSO   XSpecsAllocateView

   BUGS      TBD


XSpecsMove

   NAME
   XSpecsMove - Move graphics pen in the XSpecs three
   dimensional coordinate system

   SYNOPSIS
   Error = XSpecsMove (x, y, z)
   d0                  d0 d1 d2

   OFFSET = -150

   FUNCTION
   This function moves the position of the graphics pen in both
   the left and right rastports to positions corresponding to
   the input XSpecs (x, y, z) coordinates.  See XSpecsLeftXY
   and XSpecsRightXY for a complete definition of the XSpecs
   coordinate system.

   INPUTS
   d0 = x (16 bits)
   d1 = y (16 bits)
   d2 = z (16 bits)

   RESULT
   d0 = 0 if function successful
   d0 = 1 if attempt to move to point outside screen limits

   SEE ALSO
   XSpecsLeftXY XSpecsRightXY

   BUGS  TBD


XSpecsMoveSprite

   NAME
   XSpecsMoveSprite - Move sprite in the XSXpecs three
   dimensional coordinate system.

   SYNOPSIS
   Error = XSpecsMoveSprite(x ,y, z, xoffset, yoffset, SpriNum)
   d0                       d0 d1 d2 d3       d4       d5

   OFFSET = -96

   FUNCTION
   This function moves a simple sprite to positions in the left
   and right viewports corresponding to the input (x, y, z)
   position in the XSpecs coordinate system.  This function
   must have been preceded by XSpecsGetSprite and
   XSpecsChangeSprite.  Switching of the XSpecs Lenses will
   give the illusion that the sprite is located at the XSpecs
   (x, y, z) position.  See XSpecsLeftXY or XSpecsRightXY for a
   complete description of the XSpecs coordinate system.
      Since sprite position is measured at the upper left
   corner of the SpriteImage, it may sometimes be necessary to
   offset the sprite position on the screen to center the image
   at its intended position. Input xoffset and yoffset are
   pixel values for adjusting the sprite display in this
   manner.

   INPUTS
   d0 = x (16 bits)
   d1 = y (16 bits)
   d2 = z (16 bits)
   d3 = xoffset (# of horizontal pixels offset positive or negative)
   d4 = yoffset (# of vertical pixels offset positive or negative)
   d5 = sprite number

   RESULT
   d0 = 0 if function successful
   d0 = 1 if attempt to move outside of screen limits

   SEE ALSO
   XSpecsGetSprite XSpecsChangeSprite XSpecsLeftXY
   XSpecsRightXY

   BUGS
   TBD


XSpecsOn

   NAME
   XSpecsOn - Begin switching XSpecs lenses.

   SYNOPSIS
   UserPort = XSpecsOn (IDCMPFlags)
   d0                   d0

   OFFSET= -42

   FUNCTION
   This function starts the XSpecs vertical blank interrupt
   which switches XSpecs lenses alternately from left to right.
   This function must have been proceeded by
   XSpecsAllocateView.  XSpecs are assumed to be attached to
   joystick connector #2.  You are automatically assigned a
   UserPort for IDCMP messages.  You choose the IDCMP messages
   to be received at this port by the input value of IDCMPFlags
   in d0.

   INPUTS
   d0 = IDCMPFlags

   RESULT
   d0 = Address of UserPort if function successful
   d0 = 1 if function unsuccessful

   SEE ALSO
   XSpecsOff

   BUGS  TBD


XSpecsOff

   NAME
   XSpecsOff - Turn off XSpecs lens switching.

   SYNOPSIS
   XSpecsOff()

   OFFSET = -48

   FUNCTION
   This function turns off switching of XSpecs lenses (which
   had been initiated by XSpecsOn).

   SEE ALSO
   XSpecsOn  XSpecsAllocateView

   BUGS
   TBD


XSpecsPolyDraw

   NAME
   XSpecsPolyDraw - Draw a sequence of lines the XSpecs three
   dimensional coordinate system.

   SYNOPSIS
   Error = XSpecsPolyDraw (Points, Count)
   d0                      a0      d0

   OFFSET = -144

   FUNCTION
   This function draws a sequence of connected lines between
   points in the XSpecs left and right rastports corresponding
   to a sequence of (x, y, z) points in the XSpecs three
   dimensional coordinate system.  The switching of XSpecs
   lenses gives the illusion of a 3 dimensional sequence of
   connected lines.  This function must have been preceded by
   XSpecsAllocateView.  Lines are drawn using the current APen.
   See XSpecsLeftXY or XSpecsRightXY for a complete description of
   the XSpecs coordinate system.

   INPUTS
   d0 = Count, the number of points in sequence.
   a0 = Address of an array of 16 bit (x, y, z) values defining
        each point.

   RESULT
   d0 = 0 if function successful.
   d0 = 1 if attempt to draw outside of screen boundary

   SEE ALSO  XSpecsDraw  XSpecsAllocateView  XSpecsSetAPen

   BUGS  TBD


XSpecsRightRastPort

   NAME
   XSpecsRightRastPort - Find XSpecs right rastport address.

   SYNOPSIS
   RightRastportAddress = XSpecsRightRastPort()
   d0

   OFFSET = -120

   FUNCTION
   This function returns the address of the XSpecs right
   rastport.  This function must be preceded by
   XSpecsAllocateView.  You can use this address with any of
   the Amiga graphics functions to draw separately into the
   right rastport.  Convert XSpecs three dimensional
   coordinates to right rastport coordinates using
   XSpecsRightXY.  See XSpecsRightXY for a complete description
   of the XSpecs coordinate system.

   RESULT
   d0 = Address of right rastport

   SEE ALSO
   XSpecsAllocateView XSpecsRightXY XSpecsMove

   BUGS TBD


XSpecsRightViewPort

   NAME
   XSpecsRightViewPort - Find XSpecs right viewport address.

   SYNOPSIS
   RightViewportAddress = XSpecsRightViewPort()
   d0

   OFFSET = -132

   FUNCTION
   This function returns the address of the XSpecs right
   viewport.  This function must be preceded by
   XSpecsAllocateView.

   RESULT
   d0 = Address of right viewport

   SEE ALSO
   XSpecsAllocateView XSpecsRightXY

   BUGS TBD


XSpecsRightXY

   NAME
   XSpecsRightXY - Convert XSpecs three dimensional coordinates
   to right rastport coordinates.

   SYNOPSIS
   RightXY = XSpecsRightXY (x, y, z)
   d0                       d0 d1 d2

   OFFSET = -108

   FUNCTION
   The XSpecs coordinate system is a three dimensional system
   with an origin (0, 0, 0 position) at the exact center of the
   Amiga monitor screen.  The x direction is positive from this
   point to the right and negative to the left.  The y
   direction is positive from this position moving down and
   negative moving up.  The z direction is positive from this
   position moving into the screen and negative moving out of
   the screen toward you.  For every point (x, y, z) in XSpecs
   coordinates there is a corresponding point projected into
   the both left and right rastports.  When each of these
   points are drawn separately into the left and right
   rastports, the switching of the XSpecs lenses from left to
   right will give the illusion of a single point at the XSpecs
   (x, y, z) position.  The scale of the XSpecs coordinate
   system depends on the ViewModes selected when setting up the
   XSpecs View (XSpecsAllocateView).  For LowRes views, the
   scale is chosen as 320 units horizontally across the face of
   the monitor.  For HiRes views, the scale is chosen as 640
   units horizontally across the face of the monitor.  This
   same scale is used both horizontally and vertically
   resulting in about 440 units vertically in HiRes and 220
   units vertically in LowRes at the face of the monitor.
      This function converts the input XSpecs (x,y,z)
   coordinates into rastport coordinates in the right rastport.
   Use this function to determine the position of points in the
   right rastport corresponding to an (x,y,z) position in the
   XSpecs coordinate system.  Rastport coordinates are measured
   from the upper left corner of the screen.  The rastport is
   either 320 or 640 pixels wide (depending on ViewMode) and
   200 lines high.

   INPUTS
   d0 = x (16 bits)
   d1 = y (16 bits)
   d2 = z (16 bits)

   RESULT
   d0 = RightX (high 16 bits), RightY (low 16 bits)
   d0 = -1 if point is outside screen boundaries

   SEE ALSO
   XSpecsLeftXY

   BUGS  TBD


XSpecsSetAPen

   NAME
   XSpecsSetAPen - SetAPen in XSpecs left and right rastports.

   SYNOPSIS
   XSpecsSetAPen (PenNumber)
                  d0

   OFFSET = -54

   FUNCTION
   This function sets the graphics APen in both the XSpecs left
   and right rastports.  This function must have been preceded
   by XSpecsAllocateView.

   INPUTS
   d0 = PenNumber

   SEE ALSO
   XSpecsSetDrMd  XSpecsAllocateView

   BUGS   TBD


XSpecsSetDrMd

   NAME
   XSpecsSetDrMd - Set Draw mode in XSpecs left and right
   rastports.

   SYNOPSIS
   XSpecsSetDrMd (DrawMode)
                  d0

   OFFSET = -138

   FUNCTION
   This function sets the drawing mode in the XSpecs left and
   right rastports.  This function must have been preceded by
   XSpecsAllocateView.

   INPUTS
   d0 = DrawMode

   SEE ALSO
   XSpecsSetAPen  XSpecsAllocateView

   BUGS
   TBD


XSpecsSetRGB4

   NAME
   XSpecsSetRGB4 - Set RGB values for a color register in
   XSpecs left and right viewports.

   SYNOPSIS
   XSpecsSetRGB4 (PenNumber, R, G, B)
                  d0         d1 d2 d3
   OFFSET = -60

   FUNCTION
   This function sets RGB values for a specific color register
   in the XSpecs left and right viewports.  This function must
   have been preceded by XSpecsAllocateView.

   INPUTS
   d0 = PenNumber
   d1 = R
   d2 = G
   d3 = B

   SEE ALSO
   XSpecsLoadRGB4

   BUGS  TBD


XSpecsText

   NAME
   XSpecsText - Write text at XSpecs coordinates (x, y, z).

   SYNOPSIS
   Error = XSpecsText (Text, x, y, z, Count)
   d0                  a0    d0 d1 d2 d3

   OFFSET = -72

   FUNCTION
   This function writes text in both the XSpecs left and right
   rastports beginning at positions corresponding to the input
   Xspecs (x, y, z) coordinates.  Switching of the XSpecs
   lenses gives an illusion of a single row of text in the
   XSpecs three dimensional coordinate system.  Text is drawn
   using the current value APen.  This function must have been
   preceded by XSpecsAllocateView.  See XSpecsLeftXY or
   XSpecsRightXY for a complete description of the XSpecs
   coordinate system.

   INPUTS
   a0 = Address of text string
   d0 = x (16 bits)
   d1 = y (16 bits)
   d2 = z (16 bits)
   d3 = Count, or number of text characters

   RESULT
   d0 = 0 if function successful
   d0 = 1 if Starting Point is outside screen limits.  Function
   does not check if end of text is outside screen limits.

   SEE ALSO
   XspecsAllocateView  XSpecsLeftXY XSpecsRightXY
   XSpecsSetAPen

   BUGS TBD


XSpecsTime

   NAME
   XSpecsTime - Get Time in 1/60th of second intervals.

   SYNOPSIS
   Time = XSpecsTime()
   d0

   OFFSET = -168

   FUNCTION
   This function provides a count of the number of 1/60 second
   vertical blank intervals that have occurred since
   XSpecsOn.  This count can be used for any timing purposes in
   your program.  This function must have been preceded by
   XSpecsOn.

   RESULT
   d0 = Time

   SEE ALSO
   XSpecsOn

   BUGS      TBD


XSpecsWritePixel

   NAME
   XSpecsWritePixel - Write pixel in XSpecs three dimensional
   coordinate system.

   SYNOPSIS
   Error = XSpecsWritePixel (x, y, z)
   d0                        d0 d1 d2

   OFFSET = -78

   FUNCTION
   This function writes a pixel in both left and right XSpecs
   rastports at positions corresponding to a point (x, y, z) in
   the XSpecs three dimensional coordinate system.  The
   switching of the XSpecs lenses gives the illusion of a
   single point the XSpecs coordinate system.  The pixel is
   written using the current APen.  This function must have
   been preceded by XSpecsAllocateView. See XSpecsLeftXY or
   XSpecsRightXY for a complete description of the XSpecs
   coordinate system.

   INPUTS
   d0 = x (16 bits)
   d1 = y (16 bits)
   d2 = x (16 bits)

   RESULT
   d0 = 0 if function successful
   d0 = 1 if attempt to write outside screen limits

   SEE ALSO
   XSpecsSetAPen  XSpecsLeftXY

   BUGS  TBD