;--------------------------------------------------------------------------- NOTE, ClearScreen(NULL) is NOT allowed! This has been a MISTAKE in older autodocs! ;--------------------------------------------------------------------------- TABLE OF CONTENTS retina.library/Retina_AllocMem retina.library/Retina_AllocBitMap retina.library/Retina_AvailMem retina.library/Retina_Circle retina.library/Retina_CircleFill retina.library/Retina_ClearScreen retina.library/Retina_CloseMonitor retina.library/Retina_CloseScreen retina.library/Retina_CopyRect retina.library/Retina_DisownRetina retina.library/Retina_FindMonitor retina.library/Retina_FreeMem retina.library/Retina_FreeBitMap retina.library/Retina_GetAPen retina.library/Retina_Line retina.library/Retina_LoadPalette retina.library/Retina_MoveSprite retina.library/Retina_NextMonitor retina.library/Retina_OpenMonitor retina.library/Retina_OpenScreen retina.library/Retina_OwnRetina retina.library/Retina_ReadPixel retina.library/Retina_ReadRect retina.library/Retina_RectFill retina.library/Retina_ScreenToBack retina.library/Retina_ScreenToFront retina.library/Retina_SetAPen retina.library/Retina_SetDrMd retina.library/Retina_SetPalette retina.library/Retina_SetPixel retina.library/Retina_SetSegmentPtr retina.library/Retina_SetSprite retina.library/Retina_SpriteFunction retina.library/Retina_SwapBitMap retina.library/Retina_SwapRect retina.library/Retina_WaitTOF retina.library/Retina_WritePixel retina.library/Retina_WriteRect retina.library/Retina_OwnRetina retina.library/Retina_OwnRetina NAME OwnRetina -- get the Retina hardware for private usage SYNOPSIS OwnRetina() void OwnRetina( void ); FUNCTION If Retina is available return immediately with Retina locked for your exclusive use. If Retina is not available put task to sleep. It will be awakened as soon as Retina is available. INPUTS RESULT NOTE This call is guaranteed to preserve all registers. RETURNS SEE ALSO DisownRetina(), exec.doc/ObtainSemaphore() retina.library/Retina_DisownRetina retina.library/Retina_DisownRetina NAME DisownRetina - return Retina to free state. SYNOPSIS DisownRetina() void DisownRetina( void ); FUNCTION Free the Retina hardware for use by other Retina users. INPUTS RESULT NOTE This call is guaranteed to preserve all registers. SEE ALSO OwnRetina(), exec.doc/ReleaseSemaphore() retina.library/Retina_WriteRect retina.library/Retina_WriteRect NAME Retina_WriteRect -- Write data to Retina memory SYNOPSIS WriteRect(Mem,MemX,MemY,MemWidth,Mode,Screen,ScreenX,ScreenY,SizeX,SizeY[,Mem2]) A0 D0 D1 D2 D3 A1 D4 D5 D6 D7 [A2] void WriteRect(UBYTE *,UWORD,UWORD,UWORD,ULONG, struct RetinaSreen *,UWORD,UWORD,UWORD,UWORD [,UBYTE *]); FUNCTION Copies a rectangular area from Amiga memory to Retina memory. INPUTS Mem - A pointer to the upper left corner of the 'bitmap' in Amiga memory. (VDPaint: GB values) MemX - The left edge of the rectangle in Amiga memory. MemY - The top edge of the rectangle in Amiga memory. MemWidth - The width of the 'bitmap' in Amiga memory. Mode - one of: RECTMODE_RGB - each pixel has an R, G and B value RECTMODE_RGBA - each pixel has an R, G, B and A (alpha) value RECTMODE_BGR - same as RGB, but the pixel components in revers order RECTMODE_GB_R - For VDPaint only, do NOT use! RECTMODE_256 - each pixel has one of 256 colors RECTMODE_GB_R0 - For VDPaint only, do NOT use! Screen - a pointer to the desired Retina screen ScreenX - The left edge of the rectangle on Retina screen. ScreenY - The top edge of the rectangle on Retina screen. SizeX - The width of the rectangle. SizeY - The height of the rectangle. Mem2 - A pointer to the upper left corner of the VDPaint R 'bitmap'. For VDPaint only, do NOT use! RESULT NOTE Clipping takes place in Retina memory but not in Amiga memory! This call is guaranteed to preserve all registers. EXAMPLE BUGS RECTMODE_BGR not implemented yet. No support for 15, 16 bit. SEE ALSO ReadRect(), SwapRect(), CopyRect() retina.library/Retina_ReadRect retina.library/Retina_ReadRect NAME Retina_ReadRect -- Read data from Retina memory SYNOPSIS ReadRect(Mem,MemX,MemY,MemWidth,Mode,Screen,ScreenX,ScreenY,SizeX,SizeY[,Mem2]) A0 D0 D1 D2 D3 A1 D4 D5 D6 D7 [A2] void ReadRect(UBYTE *,UWORD,UWORD,UWORD,ULONG, struct RetinaSreen *,UWORD,UWORD,UWORD,UWORD [,UBYTE *]); FUNCTION Copies a rectangular area from Retina memory to Amiga memory. INPUTS Mem - A pointer to the upper left corner of the 'bitmap' in Amiga memory. (VDPaint: GB values) MemX - The left edge of the rectangle in Amiga memory. MemY - The top edge of the rectangle in Amiga memory. MemWidth - The width of the 'bitmap' in Amiga memory. Mode - one of: RECTMODE_RGB - each pixel has an R, G and B value RECTMODE_RGBA - each pixel has an R, G, B and A (alpha) value RECTMODE_BGR - same as RGB, but the pixel components in revers order RECTMODE_GB_R - For VDPaint only, do NOT use! RECTMODE_256 - each pixel has one of 256 colors Screen - a pointer to the desired Retina screen ScreenX - The left edge of the rectangle on Retina screen. ScreenY - The top edge of the rectangle on Retina screen. SizeX - The width of the rectangle. SizeY - The height of the rectangle. Mem2 - A pointer to the upper left corner of the VDPaint R 'bitmap'. For VDPaint only, do NOT use! RESULT NOTE Clipping takes place in Retina memory but not in Amiga memory! This call is guaranteed to preserve all registers. EXAMPLE BUGS RECTMODE_BGR not implemented yet. No support for 15, 16 bit. SEE ALSO WriteRect(), SwapRect(), CopyRect() retina.library/Retina_SwapRect retina.library/Retina_SwapRect NAME Retina_SwapRect -- Exchange data with Retina memory SYNOPSIS SwapRect(Mem,MemX,MemY,MemWidth,Mode,Screen,ScreenX,ScreenY,SizeX,SizeY[,Mem2]) A0 D0 D1 D2 D3 A1 D4 D5 D6 D7 [A2] void SwapRect(UBYTE *,UWORD,UWORD,UWORD,ULONG, struct RetinaSreen *,UWORD,UWORD,UWORD,UWORD [,UBYTE *]); FUNCTION Swaps a rectangular area between Amiga memory and Retina memory. INPUTS Mem - A pointer to the upper left corner of the 'bitmap' in Amiga memory. (VDPaint: GB values) MemX - The left edge of the rectangle in Amiga memory. MemY - The top edge of the rectangle in Amiga memory. MemWidth - The width of the 'bitmap' in Amiga memory. Mode - one of: RECTMODE_RGB - each pixel has an R, G and B value RECTMODE_RGBA - each pixel has an R, G, B and A (alpha) value RECTMODE_BGR - same as RGB, but the pixel components in revers order RECTMODE_GB_R - For VDPaint only, do NOT use! RECTMODE_256 - each pixel has one of 256 colors Screen - a pointer to the desired Retina screen ScreenX - The left edge of the rectangle on Retina screen. ScreenY - The top edge of the rectangle on Retina screen. SizeX - The width of the rectangle. SizeY - The height of the rectangle. Mem2 - A pointer to the upper left corner of the VDPaint R 'bitmap'. For VDPaint only, do NOT use! RESULT NOTE Clipping takes place in Retina memory but not in Amiga memory! This call is guaranteed to preserve all registers. EXAMPLE BUGS RECTMODE_RGB, RECTMODE_RGBA, RECTMODE_BGR, RECTMODE_256 not implemented yet. No support for 8, 15, 16 bit. SEE ALSO ReadRect(), WriteRect(), CopyRect() retina.library/Retina_CopyRect retina.library/Retina_CopyRect NAME Retina_CopyRect -- Copy data inside Retina memory. SYNOPSIS CopyRect(SrcScreen,SrcX,SrcY,DestScreen,DestX,DestY,SizeX,SizeY) A0 D0 D1 A1 D4 D5 D6 D7 void CopyRect(struct RetinaSreen *,UWORD,UWORD, struct RetinaSreen *,UWORD,UWORD,UWORD,UWORD); FUNCTION Copy data inside Retina memory. Using this function is much faster than reading and writing the data! Retina_CopyRect() can copy about seven MByte per second. INPUTS Screen2 - A pointer to the desired Retina screen (source). SrcX - The left edge of the source rectangle SrcY - The top edge of the source rectangle SrcWidth - The width of the 'bitmap' in Amiga memory. Mode - Currently unused, set to 0! Screen2 - A pointer to the desired Retina screen (destination). Screen1 and Screen2 may be identical! DestX - The left edge of the destination rectangle. DestY - The top edge of the destination rectangle. SizeX - The width of the rectangle. SizeY - The height of the rectangle. RESULT NOTE Clipping takes place in Retina memory! This call is guaranteed to preserve all registers. EXAMPLE BUGS Not implemented yet. SEE ALSO ReadRect(), WriteRect(), SwapRect() retina.library/Retina_SwapBitMap retina.library/Retina_SwapBitMap NAME Retina_SwapBitMap -- Swap the bitmaps of a double buffered screen SYNOPSIS SwapBitMap(Screen) A0 void SwapBitMap(struct RetinaSreen *); FUNCTION Swaps the bitmaps of a double buffered screen. On double buffered screens _rs_BitMap always points to the currently invisible bitmap. So all drawing operations will be invisible until the next call to Retina_SwapBitMap(). INPUTS Screen - a pointer to the desired screen RESULT NOTE Retina_SwapBitMap() waits for 'TopOfFrame' before the bitmaps are toggled and the function returns. A call to Retina_SwapBitMap() is ignored, if the screen is not double buffered. This call is guaranteed to preserve all registers. EXAMPLE BUGS SEE ALSO OpenScreen() retina.library/Retina_SetSprite retina.library/Retina_SetSprite NAME Retina_SetSprite -- Define the outline of the Retina hardware sprite SYNOPSIS success = Retina_SetSprite(Screen,Data,Height,Tags) D0 A0 A1 D0 A2 ULONG SetSprite(struct RetinaScreen *, ULONG *,UWORD,APTR); FUNCTION Define the outline of the Retina hardware sprite. The width of the sprite is always 32 pixels. Height*RepY must be in the range of 1 to 128 lines. Each pixel of the sprite is built out of two corresponding bits of two 32 bit words (see example). | 1. word | 2. word | display | +---------+---------+---------------------+ | 0 | 0 | color 0 | | 0 | 1 | color 1 | | 1 | 0 | transparent | | 1 | 1 | inverted background | INPUTS Screen - A pointer to the Retina screen, the sprite belongs to. Data - a pointer to the sprite data (see below). Data is not needed any more after Retina_SetSprite() returned, it has been copied to Retina graphics memory. Height - the height of the sprite (without repy) Tags - A pointer to a TagList with one or more of the following tags or NULL. RSP_On - turn the sprite on (ti_Data=1) or off (ti_Data=0) [default:0] RSP_Color0 - set sprite color 0, ti_Data:[0..255] [default:0] RSP_Color1 - set sprite color 1, ti_Data:[0..255] [default:1] RSP_ZoomX - set horizontal zoom, ti_Data:[1..4] [default:1] RSP_ZoomY - set vertical zoom, ti_Data:[1..128] [default:1] RESULT success - Retina_SetSprite may return 0, if there is not enough free Retina graphics memory. NOTE Retina_SetSprite() turns off the old sprite and turns on the new one! This call is guaranteed to preserve all registers except D0. EXAMPLE lea data(pc),a1 moveq #3,d0 ;height = 3 moveq #2,d1 ;Y-zoom = 2 (==> total height = 6) CALLRET SetSprite ... data: dc.l $ffffffff,$ff000000 ;line 0: 8 dots inverted background dc.l $00ffffff,$00000000 ;line 1: 8 dots sprite color 0 dc.l $00ffffff,ff0000000 ;line 2: 8 dots sprite color 1 BUGS Screen is currently unused. SEE ALSO Retina_SpriteFunction() retina.library/Retina_MoveSprite retina.library/Retina_MoveSprite NAME Retina_MoveSprite -- Move the sprite to the specified position SYNOPSIS Retina_MoveSprite(Screen,x, y) A0 D0 D1 void MoveSprite(struct RetinaScreen *,UWORD,UWORD); FUNCTION Moves the sprite to the specified position. INPUTS Screen - A pointer to the Retina screen, the sprite belongs to. x - the desired horizontal position x - the desired vertical position RESULT NOTE Retina_MoveSprite() may be called from interrupts. This call is guaranteed to preserve all registers. EXAMPLE BUGS screen - currently unused Ignores the screen resolution and the sprites horizontal zoom! SEE ALSO retina.library/Retina_SpriteFunction retina.library/Retina_SpriteFunction NAME Retina_SpriteFunction -- Function to modify several sprite parameters SYNOPSIS Retina_SpriteFunction(screen,tags) A0 A1 void SpriteFunction(struct RetinaScreen *,struct TagItem *); FUNCTION Function to modify several sprite parameters. INPUTS Screen - A pointer to the Retina screen, the sprite belongs to. Tags - one or more of the following tags: RSP_On - turn the sprite on (ti_Data=1) or off (ti_Data=0) RSP_Color0 - set sprite color 0, ti_Data:[0..255] RSP_Color1 - set sprite color 1, ti_Data:[0..255] RSP_ZoomX - set horizontal zoom, ti_Data:[1..4] RESULT NOTE This call is guaranteed to preserve all registers. EXAMPLE BUGS screen - currently unused SEE ALSO Retina_SetSprite(), retina/public.i retina.library/Retina_AvailMem retina.library/Retina_AvailMem NAME Retina_AvailMem -- Returns the amount of free graphics memory SYNOPSIS Size = Retina_AvailMem(Flags) D0 ULONG AvailMem(ULONG); FUNCTION Returns the amount of free graphics memory on the Retina board INPUTS Flags - 0 to get the amount of free memory MEMF_TOTAL to get the amount of available memory (free and used) MEMF_LARGEST to get the size of the largest free memory block. MEMF_LARGEST2 to get the size of the second largest free memory block. RESULT Size - the amount of free memory NOTE This call is guaranteed to preserve all registers except D0. EXAMPLE BUGS MEMF_LARGEST and MEMF_LARGEST2 not supported yet. SEE ALSO retina.library/Retina_AllocMem retina.library/Retina_AllocMem NAME Retina_AllocMem -- Allocate some graphics memory on the Retina board SYNOPSIS Mem = Retina_AllocMem(size,flags) D0 D0 D1 UBYTE * AllocMem(ULONG,ULONG); FUNCTION Allocate some graphics memory on the Retina board INPUTS size - the amount of memory required (in bytes) flags - MUST be 0! RESULT A pointer to the allocated memory or NULL NOTE The total size of allocated memory will be rounded up to a multiple of 64. The start address will be a multiple of 64. This call is guaranteed to preserve all registers except D0. EXAMPLE BUGS SEE ALSO Retina_AllocBitMap, Retina_FreeMem retina.library/Retina_FreeMem retina.library/Retina_FreeMem NAME Retina_FreeMem -- Free the memory allocated with Retina_AllocMem SYNOPSIS Retina_FreeMem(Mem) A0 void FreeMem(UBYTE *); FUNCTION Free some graphics memory on the Retina board INPUTS Mem - the pointer returned by Retina_AllocMem RESULT NOTE Mem may be NULL This call is guaranteed to preserve all registers. EXAMPLE BUGS SEE ALSO Retina_AllocMem retina.library/Retina_FreeBitMap retina.library/Retina_FreeBitMap NAME Retina_FreeBitMap -- Free the memory allocated with Retina_AllocBitMap SYNOPSIS Retina_FreeBitMap(Mem) A0 void FreeBitMap(UBYTE *); FUNCTION Free some graphics memory on the Retina board INPUTS Mem - the pointer returned by Retina_AllocBitMap RESULT NOTE Mem may be NULL This call is guaranteed to preserve all registers. EXAMPLE BUGS SEE ALSO Retina_AllocBitMap retina.library/Retina_AllocBitMap retina.library/Retina_AllocBitMap NAME Retina_AllocBitMap -- Allocate display memory on the Retina board SYNOPSIS Mem = Retina_AllocBitMap(width,height,bytesPerPixel,flags) D0 D0 D1 D2 D3 UBYTE * AllocBitMap(UWORD,UWORD,UWORD,ULONG); FUNCTION Allocate the graphics memory on the Retina board, which is necessary for an 'invisible' screen. INPUTS width - the width of the screen (pixels) height - the height of the screen (lines) bytesPerPixel - the number of bytes per pixel (1 for 256 colors, 2 for 15(16) bit true color and 3 for 24 bit true color) flags - MUST be 0! RESULT A pointer to the allocated memory or NULL. NOTE Width is rounded up to the next multiple of 8. The total size of allocated memory will be rounded up to a multiple of 64. The start address will be a multiple of 64. This call is guaranteed to preserve all registers except D0. EXAMPLE BUGS SEE ALSO Retina_AllocMem, Retina_FreeBitMap retina.library/Retina_Circle retina.library/Retina_Circle NAME Retina_Circle -- Draws a circle SYNOPSIS Retina_Circle(Screen,x, y, r) A0 D0 D1 D2 void Circle(struct RetinaSreen *,UWORD,UWORD,UWORD); FUNCTION Draws a circle using the color set with SetAPen() before. INPUTS Screen - a pointer to an open Retina screen x,y - the coordinates of the center of the circle r - the radius of the circle (half the diameter) RESULT NOTE This call is guaranteed to preserve all registers. This function does support RDM_COMPLEMENT. EXAMPLE BUGS Only for 8 and 24 bit modes. SEE ALSO Retina_SetAPen(), Retina_CircleFill() retina.library/Retina_CircleFill retina.library/Retina_CircleFill NAME Retina_CircleFill -- Draws a filled circle SYNOPSIS Retina_CircleFill(Screen,x, y, r) A0 D0 D1 D2 void CircleFill(struct RetinaSreen *,UWORD,UWORD,UWORD); FUNCTION Draws a filled circle using the color set with SetAPen() before. INPUTS Screen - a pointer to an open Retina screen x,y - the coordinates of the center of the filled circle r - the radius of the circle (half the diameter) RESULT NOTE This call is guaranteed to preserve all registers. This function does support RDM_COMPLEMENT on 24 bit screens. EXAMPLE BUGS Only for 8 and 24 bit modes. SEE ALSO Retina_SetAPen(), Retina_Circle() retina.library/Retina_WritePixel retina.library/Retina_WritePixel NAME Retina_WritePixel -- Draws a pixel SYNOPSIS Retina_WritePixel(Screen,x, y) A0 D0 D1 void WritePixel(struct RetinaSreen *,UWORD,UWORD); FUNCTION Draws a pixel using the color set with Retina_SetAPen() before. INPUTS Screen - a pointer to an open Retina screen x,y - the coordinates of the pixel RESULT NOTE This call is guaranteed to preserve all registers. This function does support RDM_COMPLEMENT. EXAMPLE BUGS Only for 8 and 24 bit modes. SEE ALSO Retina_SetAPen(), SetPixel(), ReadPixel() retina.library/Retina_SetPixel retina.library/Retina_SetPixel NAME Retina_SetPixel -- Draws a pixel SYNOPSIS Retina_SetPixel(Screen,x, y, Color) A0 D0 D1 D2 void SetPixel(struct RetinaSreen *,UWORD,UWORD,ULONG); FUNCTION Draws a pixel using the specified Color. INPUTS Screen - a pointer to an open Retina screen x,y - the coordinates of the pixel Color - the desired color 00RRGGBB 00 - reserved, MUST be 00 RR - the red component on true color screens GG - the green component on true color screens BB - the blue component on true color screens or the number of the palette register on a 256 color screen RESULT NOTE This call is guaranteed to preserve all registers. This function does support RDM_COMPLEMENT (Color is ignored). EXAMPLE BUGS Only for 8 and 24 bit modes. SEE ALSO WritePixel(), ReadPixel() retina.library/Retina_ReadPixel retina.library/Retina_ReadPixel NAME Retina_ReadPixel -- Reads a pixel SYNOPSIS Color = Retina_ReadPixel(Screen,x, y) D0 A0 D0 D1 ULONG ReadPixel(struct RetinaSreen *,UWORD,UWORD); FUNCTION Reads a pixel from the specified coordinates. INPUTS Screen - a pointer to an open Retina screen x,y - the coordinates of the pixel RESULT color - the desired color 00RRGGBB 00 - reserved, currently always 00 RR - the red component on true color screens GG - the green component on true color screens BB - the blue component on true color screens or the number of the palette register on a 256 color screen NOTE This call is guaranteed to preserve all registers except D0. EXAMPLE BUGS Only for 8 and 24 bit modes. SEE ALSO WritePixel(), SetPixel() retina.library/Retina_Line retina.library/Retina_Line NAME Retina_Line -- Draw a line SYNOPSIS Retina_Line(Screen,x1,y1,x2,y2) A0 D0 D1 D2 D3 void Line(struct RetinaSreen *,UWORD,UWORD,UWORD,UWORD); FUNCTION Draws a line using the color set with SetAPen() before. INPUTS Screen - a pointer to an open Retina screen x1,y1 - the start point of the line x2,y2 - the end point of the line RESULT NOTE This call is guaranteed to preserve all registers. Retina_Line() does support RDM_COMPLEMENT on 24 bit screens. EXAMPLE BUGS No support for 15, 16 bit. Retina_Line does not do any clipping! SEE ALSO Retina_SetAPen() retina.library/Retina_RectFill retina.library/Retina_RectFill NAME Retina_RectFill -- Draw a rectangle SYNOPSIS Retina_RectFill(Screen,x1,y1,x2,y2) A0 D0 D1 D2 D3 void RectFill(struct RetinaSreen *,UWORD,UWORD,UWORD,UWORD); FUNCTION Draws a rectangle using the color set with SetAPen() before. INPUTS Screen - a pointer to an open Retina screen x1,y1 - the top left corner x2,y2 - the bottom right corner RESULT NOTE This call is guaranteed to preserve all registers. EXAMPLE BUGS No support for 15, 16 bit. On 256 color screens the three lower bits of x1 and x2 are ignored. Very slow on 24 bit screens. SEE ALSO Retina_SetAPen() retina.library/Retina_SetAPen retina.library/Retina_SetAPen NAME Retina_SetAPen -- Set the main pen SYNOPSIS Retina_SetAPen(Screen,color) A0 D0 void SetAPen(struct RetinaSreen *,ULONG); FUNCTION Sets the pen used for all drawing operations INPUTS Screen - a pointer to an open Retina screen color - the desired color 00RRGGBB 00 - reserved, MUST be 00 RR - the red component on true color screens GG - the green component on true color screens BB - the blue component on true color screens or the number of the palette register on a 256 color screen RESULT NOTE This call is guaranteed to preserve all registers. EXAMPLE BUGS SEE ALSO retina.library/Retina_SetDrMd retina.library/Retina_SetDrMd NAME Retina_SetDrMd -- Set the main drawing mode SYNOPSIS Retina_SetDrMd(Screen,mode) A0 D0 void SetDrMd(struct RetinaSreen *,ULONG); FUNCTION Sets the drawing mode used for all drawing operations INPUTS Screen - a pointer to an open Retina screen Mode RDM_JAM1 - All drawing commands use the color set by Retina_SetAPen() before. RDM_COMPLEMENT - For each 1 bit of the drawn data the corresponding bit in the target area on the Retina screen is complemented. RESULT NOTE This call is guaranteed to preserve all registers. EXAMPLE BUGS This function works fine, but almost all other functions do NOT take care of the selected drawmode! So be careful and always reset the drawmode to its normal state (RDM_JAM1) to avoid problems with future releases of retina.library! SEE ALSO retina.library/Retina_GetAPen retina.library/Retina_GetAPen NAME Retina_GetAPen -- Get the main pen SYNOPSIS color = Retina_GetAPen(Screen) D0 A0 ULONG GetAPen(struct RetinaSreen *); FUNCTION Gets the pen used for all drawing operations INPUTS Screen - a pointer to an open Retina screen RESULT color - the current color 00RRGGBB 00 - reserved, always 00 RR - the red component on true color screens GG - the green component on true color screens BB - the blue component on true color screens or the number of the palette register on a 256 color screen NOTE This call is guaranteed to preserve all registers except D0. EXAMPLE BUGS SEE ALSO retina.library/Retina_ScreenToBack retina.library/Retina_ScreenToBack NAME Retina_ScreenToBack -- Put a screen to the back. SYNOPSIS ScreenToBack(Screen) A0 void ScreenToBack(struct RetinaSreen *); FUNCTION Puts the specified screen behind all other screens. INPUTS Screen - A pointer to the desired screen or NULL. If Screen is NULL the frontmost screen will be put to the back. RESULT NOTE Retina_ScreenToBack() waits for 'TopOfFrame' before the screen is moved and the function returns. This call is guaranteed to preserve all registers. EXAMPLE BUGS SEE ALSO Retina_ScreenToFront() retina.library/Retina_ScreenToFront retina.library/Retina_ScreenToFront NAME Retina_ScreenToFront -- Get a screen to the front. SYNOPSIS ScreenToFront(Screen) A0 void ScreenToFront(struct RetinaSreen *); FUNCTION Gets the specified screen in front of all other screens. INPUTS Screen - A pointer to the desired screen or NULL. If Screen is NULL the backmost screen will be put to the front. RESULT NOTE Retina_ScreenToFront() waits for 'TopOfFrame' before the screen is moved and the function returns. This call is guaranteed to preserve all registers. EXAMPLE BUGS SEE ALSO Retina_ScreenToBack() retina.library/Retina_SetSegmentPtr retina.library/Retina_SetSegmentPtr NAME Retina_SetSegmentPtr -- sets the primary host offset SYNOPSIS Ptr=Retina_SetSegmentPtr(Address) D0 A0 UBYTE * Retina_SetSegmentPtr(UBYTE *); FUNCTION Sets the primary host offset to the desired address. After a call to Retina_SetSegmentPtr() all read and write accesses will use this address. INPUTS Address - An address inside the 4MByte Retina graphics memory RESULT Ptr - A pointer to the desired address. Note, this pointer points to an address inside the 64 KByte segment in the Amiga autoconfig memory space. If you want to access more than 64 KByte, you have to call Retina_SetSegmentPtr() again. NOTE This call is guaranteed to preserve all registers except D0. EXAMPLE BUGS SEE ALSO retina.library/Retina_WaitTOF retina.library/Retina_WaitTOF NAME Retina_WaitTOF -- Wait for the top of the next video frame. SYNOPSIS WaitTOF() void WaitTOF( void ); FUNCTION Wait for vertical blank to occur before returning to caller. While waiting the calling task goes asleep, so no cpu time will be wasted. INPUTS RESULT Places this task on the TOF wait queue. When the Retina vertical blank interupt comes around, the interrupt service routine will fire off signals to all the tasks doing WaitTOF. The highest priority task ready will get to run then. NOTE This call is guaranteed to preserve all registers. EXAMPLE BUGS SEE ALSO retina.library/Retina_OpenMonitor retina.library/Retina_OpenMonitor NAME Retina_OpenMonitor - Open a new monitor SYNOPSIS Monitor = Retina_OpenMonitor(NewMonitor) D0 A0 struct RetinaMonitor * Retina_OpenMonitor(struct NewRetinaMonitor *) FUNCTION Open a new monitor. With this function you may add special types of monitor definitions to the library. INPUTS NewMonitor - A pointer to struct NewRetinaMonitor. RESULT Monitor - A pointer to struct RetinaMonitor or NULL if it could not be opened. NOTE This call is guaranteed to preserve all registers except D0. EXAMPLE BUGS SEE ALSO Retina_CloseMonitor() retina.library/Retina_CloseMonitor retina.library/Retina_CloseMonitor NAME Retina_CloseMonitor - Close a monitor SYNOPSIS Retina_CloseMonitor(Monitor) A0 void Retina_CloseMonitor(struct RetinaMonitor *) FUNCTION Closes a previously opened monitor. Before closing retina.library, you MUST close all monitors you opened! INPUTS Monitor - A pointer to struct RetinaMonitor. RESULT NOTE This call is guaranteed to preserve all registers. EXAMPLE BUGS SEE ALSO Retina_OpenMonitor() retina.library/Retina_FindMonitor retina.library/Retina_FindMonitor NAME Retina_FindMonitor - Get a pointer to a specified monitor SYNOPSIS Monitor = Retina_FindMonitor(MonitorID,Name) D0 D0 A0 struct RetinaMonitor * Retina_FindMonitor(ULONG,UBYTE*) FUNCTION Get a pointer to a struct RetinaMonitor. INPUTS MonitorID - The ID of the desired monitor. If 0, Name will be used to specify the monitor. Name - Name is the name of the desired monitor. It is optional and only used, if MonitorID is 0. RESULT Monitor - the desired pointer or NULL if not found NOTE This call is guaranteed to preserve all registers except D0. EXAMPLE BUGS SEE ALSO Retina_NextMonitor() retina.library/Retina_NextMonitor retina.library/Retina_NextMonitor NAME Retina_NextMonitor - Get a pointer to the next monitor SYNOPSIS Monitor = Retina_NextMonitor(Monitor) D0 A0 struct RetinaMonitor * Retina_NextMonitor(struct RetinaMonitor *) FUNCTION Get a pointer to the struct RetinaMonitor of the next available monitor. Using this function you may get a list of all available monitors. (see example) INPUTS Monitor - a pointer to a monitor or NULL to get the first monitor in the list. RESULT Monitor - the next monitor in the list or NULL if there are no more monitors in the list NOTE This call is guaranteed to preserve all registers except D0. EXAMPLE Go through the list of all available monitors: suba.l a0,a0 ;set A0 to NULL Loop: CALLRET NextMonitor ;get the first/next pointer movea.l d0,a0 ;pointer into A0 tst.l d0 ;reached the end? bne Loop ;no, not yet BUGS SEE ALSO Retina_FindMonitor() retina.library/Retina_SetPalette retina.library/Retina_SetPalette NAME Retina_SetPalette - Load a single color value. SYNOPSIS Retina_SetPalette(Screen,Index,Red,Green,Blue) A0 D0 D1 D2 D3 void Retina_SetPalette(struct RetinaScreen *,UWORD,UBYTE,UBYTE,UBYTE) FUNCTION Loads a single color value into the palette of the specified screen. INPUTS Screen - the desired screen Index - The desired register [0..255] Red - the red intensity [0..255] Green - the green intensity [0..255] Blue - the blue intensity [0..255] RESULT NOTE This call is guaranteed to preserve all registers. EXAMPLE ... movea.l a2,a0 ;screen move.w #2,d0 ;The desired register move.b #170,d1 ;the red intensity move.b #170,d2 ;the green intensity move.b #255,d3 ;the blue intensity CALLRET SetPalette ;set this value ... BUGS - Currently the palette is not active with all monitor types! SEE ALSO Retina_LoadPalette() retina.library/Retina_LoadPalette retina.library/Retina_LoadPalette NAME Retina_LoadPalette - Load a color palette. SYNOPSIS Retina_LoadPalette(Screen,First,Count,Table) A0 D0 D1 A1 void Retina_LoadPalette(struct RetinaScreen *,UWORD,UWORD,UBYTE*) FUNCTION Loads the palette of the specified screen. INPUTS Screen - The desired screen First - A number from 0 to 255 which specifies the register to be loaded with the first color in Table. Count - The number of color values to be loaded Table - A pointer to the RGB data or NULL. If Table=NULL, First=0 and Count=256 the registers will be initialized with default grey-levels. RESULT NOTE This call is guaranteed to preserve all registers. EXAMPLE ... movea.l a2,a0 ;screen moveq #0,d0 ;start with register 0 moveq #4,d1 ;4 colors to load lea rgb,a1 ;the pointer to the desired colors CALLRET LoadPalette ;load the values ... rgb: dc.b 0,0,0 ;color 0: black dc.b 255,0,0 ;color 1: red dc.b 0,0,255 ;color 2: blue dc.b 255,255,0 ;color 3: yellow ... BUGS - Currently the palette is not active with all monitor types! SEE ALSO Retina_SetPalette() retina.library/Retina_OpenScreen retina.library/Retina_OpenScreen NAME Retina_OpenScreen - Open a screen SYNOPSIS Screen = Retina_OpenScreen(Width,Height,ID,Flags,Tags) D0 D0 D1 D2 D3 A0 struct RetinaScreen * Retina_OpenScreen(UWORD,UWORD,ULONG,ULONG,APTR) FUNCTION Opens a screen and initializes the palette to default grey levels. INPUTS Width - Desired width, RSCR_STDWIDTH or RSCR_MAXWIDTH. It is save to specify a Width of 0. Height - Desired height, RSCR_STDHEIGHT or RSCR_MAXHEIGHT. It is save to specify a Height of 0. ID - Type of screen. See retina/public.i MID_xxx. With MID_DEFAULT_xx you can open the default screen, specified externally with 'RetinaScreenMode'. Using Retina_NextMonitor() you can look for all available MonitorIDs. Flags - These and some additional Retina screen flags are defined in 'retina/public.i'. RSFF_DONTCLEARONOPEN - Do not clear the screens bitmap when opened. If you set this, you may see random data on the opened screen. RSFF_DONTCLEARONCLOSE - Keep the screen visible after closing it. The screen will be closed and all its memory freed. The screens data will stay visible if the closed screen was the only open screen until an other screen is opened. If there were other screens, this flag has no effect. RSFF_DOUBLEBUFFER - Allocate a 2. bitmap for double buffering. See Retina_SwapBitMap() for more information. RSFF_AUTOADJUST - Reduce the desired width and/or height if it is too large or there is insufficient memory. If your software is able to handle screens of any size (it should), please set this flag. So you can be quiet sure to get a screen even under unfavourable conditions. Tags - A pointer to a TagList or NULL. RSA_BitMap - Use this BitMap, do not allocate another BitMap. The BitMap MUST have been allocated using Retina_AllocBitMap()! RSA_DBufBitMap - Same as RSA_BitMap, but used as the second bitmap for a double buffered screen. RSA_ErrorCode - ti_Data points to a ULONG in which retina.library will stick an extended error code if Retina_OpenScreen() fails. Possible values for RSA_ErrorCode are: ROSERR_NONE - everything ok or unknown error ROSERR_ID - unknown monitor-ID ROSERR_DEFAULTID - unknown default monitor-ID ROSERR_TOOBIG - screen size is too big ROSERR_NOMEM - couldn't get normal memory ROSERR_NORETINAMEM - couldn't get Retina graphics memory RESULT A pointer to a struct RetinaScreen or NULL. NOTE If you use at least one out of RSFF_AUTOADJUST, RSCR_STDWIDTH, RSCR_STDHEIGHT, RSCR_MAXWIDTH or RSCR_MAXHEIGHT, you MUST CHECK AND USE BOTH the values in _rs_Width AND _rs_Height after opening the screen! This call is guaranteed to preserve all registers except D0. EXAMPLE BUGS RSFF_AUTOADJUST currently does not support low memory conditions. RSA_DBufBitMap - not supported yet SEE ALSO Retina_SwapBitMap(), retina/public.i retina.library/Retina_CloseScreen retina.library/Retina_CloseScreen NAME Retina_CloseScreen - Close a screen SYNOPSIS Retina_CloseScreen(Screen) A0 void Retina_CloseScreen(struct RetinaScreen *) FUNCTION Closes a screen INPUTS Screen - Pointer to struct RetinaScreen or NULL RESULT NOTE This call is guaranteed to preserve all registers. EXAMPLE BUGS SEE ALSO retina.library/Retina_ClearScreen retina.library/Retina_ClearScreen NAME Retina_ClearScreen - Clear a screen SYNOPSIS Retina_ClearScreen(Screen) A0 void Retina_ClearScreen(struct RetinaScreen *) FUNCTION Clears a screen INPUTS Screen - Pointer to struct RetinaScreen RESULT NOTE Some older docs allowed NULL for Screen. This is false! Retina_ClearScreen() will crash if Screen is NULL! This call is guaranteed to preserve all registers. EXAMPLE BUGS Has some problems on the right side and on the bottom. SEE ALSO