****************************************************************** 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