P96 Driver Development

The data for the card and the chip functions are held in one control structure, the BoardInfo structure. Each card receives one board info structure; its members keep the state of the card, and provide functions through which the rtg.library programs the card and the VGA chip on the card. As a service, the rtg.library also provides there library base registers to important system libraries. This structure is defined in boardinfo.h (for C code) and boardinfo.i (for 68K assembler).

Chip and card drivers do not have access to their own library basis when called through the functions in the BoardInfo structure, i.e. base register a6 remains unset and has an unspecified value. To store private state information beyond the data made available in the documented fields of the BoardInfo structure, chip drivers may use the members bi->ChipData, and card drivers may use the members bi->CardData. Each of these members consist of 16 32-bit long words that may be used as necessary by the chip or card drivers.

Note again that a chip and card driver responsible for the same board share the same BoardInfo structure.

FindCard

FindCard is called in the first stage of the board initialisation and configuration and is used to look for a free and unconfigured board of the type the driver is capable of managing. If it finds one, it immediately reserves it for use by P96 in order to ensure that the found board is only used by a single driver.

This step is typically performed by clearing the CDB_CONFIGME bit in the flags field of the struct ConfigDev of the board, however, other methods for reserving a board for P96 may be necessary, though such functionality is specific to a particular board type and are beyond the scope of this document.

This function should also populate members of the BoardInfo structure, such as:

bi->MemoryBase to the base address of the video memory of the board in the amiga memory map

bi->MemorySize to the amount of video memory in bytes available on the board

bi->RegisterBase to the base address of the IO ports of the chip. This register bank provides the address and port registers through which legacy VGA hardware is programmed.

bi->MemoryIOBase to the base address of memory-mapped (non-VGA port based) registers of the chip, if any. Registers in this bank are addressed directly without going through a port register. If no directly addressable registers are provided by the chip, this member shall remain uninitialized.

bi->MaxPlanarMemory by the maximal size of memory addressable in a planar video mode. Due to legacy reasons, MaxPlanarMemory may remain at its default value 0. In such a case, the rtg.library assumes that the maximal addressable planar memory is one quarter of the regular memory, or 256K, whichever of these two values is smaller.

InitCard

InitCard shall perform second-stage initialization of the card after the rtg.library initialized itself. This call shall open the corresponding chip driver through OpenLibrary() if a chip driver is needed. It retrieves additional ToolTypes that stem from the monitor icon which triggered the initiaization of the card. These ToolTypes come in a form of a NULL terminated array of C-strings, with argument/value pairs separated by an equals ("=") sign; they provide card-specific settings that may be parsed by this call to adjust card or chip settings.

This function shall first fill in members of the BoardInfo structure that are card-specific and whose initialization is required prior initialization of the chip, such as:

bi->BoardType shall be updated to identify the board. This member is used by the preferences program to assign a name to the settings. Board types are allocated by iComp.

bi->PaletteChipType to the type of the RAMDAC used on the board, i.e. the chip that performs palette lookup. In case the RAMDAC is internal to the chip, this type is identical to the chip type and initialization may be deferred to the chip driver. Palette chip types are allocated by iComp.

bi->ChipFlags may be updated according to the capabilities of the card. Otherwise, the chip driver shall initialize this member.

bi->HardInterrupt may be initialized and registered through AddIntServer(). If the board supports a vertical blank interupt, the bit BIB_VBLANKINTERRUPT shall be set in bi->Flags. A typical interrupt would be a vertical retrace interrupt. On which interrupt level interrupts are triggered is board specific.The interrupt server shall clear the hardware interrupt, and then trigger the software interrupt in bi->SoftInterrupt via the exec Cause() function. This delegation limits the execution of the interrupt itself to the absolute minimum.

The bi->SetInterrupt function pointer shall be initialized to enable or disable board specific interrupts if bi->Flags indicate that the board supports a VBI interrupt.

If the chip on the card requires an external clock generator, the card driver shall also initialize the bi->PixelClockCount[] array. This array is indexed by the mode type (not the RGBType) and contains the number of different pixel clocks the clock generator is able to feed to the graphics chip for the given mode. In case the chip on the card provides an internal clock generator, this array may also be initialized by the chip driver, or the chip driver may override the settings of the card driver. The number of available clocks may depend on the BIF_OVERCLOCK flag in bi->Flags.

After board services are initialized, the call shall proceed with initializing the chip driver through its InitChip() vector. If no separate chip driver is used, this step will be skipped.

The board driver may then, afterwards, update or modify fields in struct BoardInfo that are different from the defaults provided by the Chip driver, and adjust settings according to the ToolTypes parameter.

Examples for deviating from the chip defaults are that the board may swap the red and blue outputs of the chip to provide a 24bit RGB output, or the RAM layout may be different from what the chip driver expects by default.

InitChip

InitChip is part of the chip driver interface if a separate chip driver is used by the card driver. It will be called through InitCard() of the card driver, and there shall initialize the VGA chip to defaults. It shall also initialize all chip-specific function pointers in struct BoardInfo.

Note that the card driver may override the defaults provided by the chip driver if necessary.

The following members of the BoardInfo shall be initialized:

bi->GraphicsControllerType to the type of VGA chip used.

bi->Flags to indicate board specific flags and features, see boardinfo.h

bi->RGBFormats to the RGB modes the chip or chip/RAMDAC combination is capable of.

bi->SoftSpriteFlags to a mask that identifies which modes do not allow a hardware sprite and require rendering a soft-sprite. Control over the software sprite can be further refined through the bi->EnableSoftSprite function in the BoardInfo structure, see below.

bi->MaxHorValue[] and bi->MaxVerValue[] to the maximal frame size value the chip allows. Both are arrays indexed by the mode type (not the RGBType). These values are used by the preferences program to limit the maximum frame size users may enter.

bi->MaxHorResolution[] and bi->MaxVerResolution[] to the maximal mode width and height the chip is able to generate. Both are arrays indexed by the mode type (not the RGBType). These values limit the maximal amount of pixels visible on a screen without panning.

bi->MaxBMWidth and bi->MaxBMHeight to the maximum bitmap size the card is able to represent. The bitmap size is the maximal dimension of a bitmap that may be displayed *including panning*. Additional restrictions on the bitmap size stem from the maximal available board memory. These two members are initialized to 4096 by default but may be modified as needed.

Furthermore, the chip function shall initialize all function pointers in the BoardInfo structure listed in this document.

P96 hierarchy overview

Writing a new Driver

As a guideline, the following steps should be followed when starting a new driver from scratch:

get the driver to work as a dumb frame buffer,
get the optional hardware sprite working,
get the blitter working,
add special features like flicker fixer, video modules and stuff.

Overview

Basic Functionality

What is needed to get a card to work as a basic dumb frame buffer?

Constant data

RegisterBase (optional) - a pointer to the VGA port-addressed registers
MemoryBase - a pointer to the video memory in the Amiga memory map
MemoryIOBase (optional) - a pointer to memory-mapped (extended) registers
MemorySize - size of the available video memory in bytes
MaxPlanarMemory (optional) - maximal size of a plane in planar memory
MemorySpaceBase (optional) - pointer to a region in which all apperture mappings of the board appear
MemorySpaceSize (optional) - entire size of all apperture mappings of the board
BoardName - human-readable name of the board
BoardType - identifier for the board
BitsPerCannon - bit precision for palette based modes
Flags - identifies board capabilities
SoftSpriteFlags - identifies modes not able to support hardware sprites
RGBFormats - identifies which RGB modes are provided
MaxHorValue[MAXMODES] - maximum register value per RGB mode the chip can take for horizontal timing
MaxVerValue[MAXMODES] - maximum register value per RGB mode the chip can take for vertical timing
MaxHorResolution[MAXMODES] - maximum horizontal pixel count per RGB mode
MaxVerResolution[MAXMODES] - maximum vertical pixel count per RGB mode
PixelClockCount[MAXMODES] - maximum pixel clock values per RGB mode

Functions

SetSwitch - disable/enable the VGA pass-through switch
SetColorArray - installs the palette
SetDAC - sets the RAMDAC/RGB mode
SetGC - sets the graphics mode
SetPanning - pans screens
CalculateBytesPerRow - computes the width of bitmaps
CalculateMemory - computes the base address of a bitmap
GetCompatibleFormats - provides which modes can be held simultaneously on the board
SetDisplay - enables or disables the display
ResolvePixelClock - computes a pixel clock index from a target frequency
GetPixelClock - retrieves current pixel clock as index
SetClock - sets the pixel clock from a clock index
SetMemoryMode - sets the apperature
SetWriteMask (optional) - sets writable planes in planar mode
SetClearMask (optional) - sets which planes are cleared in planar mode
SetReadPlane (optional) - sets which planes are read in planar mode
WaitVerticalSync - wait for vertical retrace
GetVSyncState (optional) - returns an indicator whether the card is in vertical sync

Hardware Sprite Support

What is needed to get a card to work with hardware sprite?

SetSprite - turns the sprite on or off
SetSpritePosition - sets the sprite position
SetSpriteImage - installs the shape of the sprite
SetSpriteColor - sets the colors of the sprite
EnableSoftSprite (optional) - checks whether a hardware sprite is available

Blitter Support

What is needed to get a card to work with blitter accelleration?

If 2D acceleration functions are provided by the chip, the rtg.library may profit from them by providing functions that redirect graphic primitives to the chip. All of the following functions are optional in the sense that the rtg.library always provides a safe default which performs the corresponding graphics primitive by the CPU, except for WaitBlitter() which shall be present if hardware accelleration is used.

Each of the functions below except for WaitBlitter() is paired by a corresponding "Default" function that implements the operation by the CPU, and to which a chip-specific implementation may fall back if the requested mode/functionality is not available through hardware acceleration.

WaitBlitter - wait for the 2D acceleration to complete
BlitPlanar2Chunky - convert a planar bitmap to indexed color
FillRect - fill a rectangle with a solid color
InvertRect - invert a rectangle
BlitRect - copy a rectangular region through a mask
BlitTemplate - expands a single bitplane to color values
BlitPattern - fills a rectangle with a pattern
DrawLine - draws a line
BlitRectNoMaskComplete - copy a rectangle by a minterm, whihtout a mask
BlitPlanar2Direct - convert a planar bitmap to direct color

Screen Dragging Support

What is needed to support screen dragging?

SetSplitPosition - set the position at which the output is split

Optionally, your graphics card may also support two palettes and switch to the second palette at the screen split position.See the SetColorArray function and the BIB_PALETTESWITCH bit on how to support this feature.

Optionally, your graphics card may also support displaying two different screen modes on the same monitor, switching the RGB mode midscreen. To indicate that this feature is supported, set the BIB_DACSWITCH bit and see the SetDAC function and the following:

GetCompatibleDACFormats - identify modes that can be shown simultaneously
CoerceMode - provide information on mode resolutions when two different modes share the same screen

Extra Stuff

SetInterrupt - enables or disables board interrupts
ResetChip - reset chip after a direct access (currently unused)
SetDPMSLevel - set monitor power savings level

Special Features

My board has unusual hardware options that need special support These functions are used to provide picture-in-picture support, video overlays or on-board flicker-fixer hardware.

GetFeatureAttrs - retrieve attributes of a special feature
CreateFeature - create a special feature such as an overlay
SetFeatureAttrs - set attributes of a special feature
DeleteFeature - remove a special feature

Memory Management

I have to override the P96 memory management functions because my memory has to be treated specially

AllocCardMem
FreeCardMem
AllocCardMemAbs
ReInitMemory

Driver private data

I need some space to put some driver private data The following members of the BoardInfo structure are reserved for the chip and card driver; the rtg.library does not touch them:

ChipFlags
CardFlags
ChipData
CardData

In Detail

Constant data

RegisterBase

A pointer to the port-based legacy VGA registers in the Amiga memory map. The rtg.library is not using this pointer, it is rather stored here for the driver itself. For example, the legacy VGA sequencer index register would be at offset 0x3c4 from this base address. Both the card and the chip driver may access this pointer. It is typically initialized by the card driver and used by the chip driver.

MemoryBase

The base address of the video RAM of the card, in the Amiga memory map. The rtg.library adminstrates this video RAM, and may also access this memory.

MemoryIOBase

The base address of memory mapped IO registers of the chip, if such an area exists. Other than the index/port based legacy VGA registers, registers in this area can be accessed directly. The rtg.library does not use this pointer, though third-party 3D drivers may use this base address to access the 3D engine of the chip, if it exists. It is typically initialized by the card driver, and used by the chip driver.

MemorySize

This is the size of available video memory for all but the planar RGB modes, excluding the size of video memory required for driver internal usage, such as buffers for sprite data or blitting. That is, this member indicates the size of the video memory available for the rtg.library. It adminstrates this data and allocates screen bitmaps and graphics data from it.

MaxPlanarMemory

This is the size in bytes of the memory available for planar display modes, using the legacy VGA planar bitplane organization. Typically, less than the total amount of board memory is available in planar modes. If this field is not filled by the chip or card driver, the rtg.library assumes 256K of planar memory, or one quarter of the total memory size available, whatever size is smaller. This field is new in v42 (release 3.0) of the rtg.library. Note that this is the memory size in bytes of one plane of VGA memory. P96 will switch between planes by means of the VGA graphics controller via SetWriteMask(), SetReadPlane() and SetClearMask().

MemorySpaceBase

The base address of all aperture regions of the video RAM in the 68K memory map. It is used to set the MMU of 040 or 060 processor boards to use non-serialised or imprecise caching mode respectively. Shall be defined if BoardInfo flag BIF_CACHEMODECHANGE is set.

MemorySpaceSize

The size of all aperture regions in the 68K address space, used to adjust their MMU mapping on the 040 or 060 processors. Shall be defined if the BoardInfo flag BIF_CACHEMODECHANGE is set.

MaxBMWidth

The maximum width of an off-screen or on-screen bitmap in pixels the board can possibly hold. This number limits the allocation of bitmaps to those whose width are smaller or equal than this size. If the target bitmap is wider, the memory allocation fails right away. This field is initialized to 4096.

MaxBMHeight

The maximum height of an off-screen or on-screen bitmap in pixels the board can possibly hold. This number limits the allocation of bitmaps to those whose height are smaller or equal than this size. If the target bitmap is wider, the memory allocation fails right away. This field is initialized to 4096.

BoardName

A pointer to the name of your board, as it will be shown in dialogs; this name shall be supplied by the card driver. For example, this may be "PicassoIV".

BoardType

This member identifies the board type; it shall be one of the values of the BTYPE enumeration in boardinfo.h. New board types will be assigned by the P96 development team on request. The rtg.library uses this value to enable board-specific workarounds or patches.

BitsPerCannon

The number of significant bits the RAMDAC uses in CLUT (palette) based modes. Usually either 6 (64 different shades) or 8 (256 shades) bits per gun (i.e. channel).

Flags

This bit field identifies the features available by the board. This bitfield is roughly divided into hardware specific features, and system features.
First the hardware bits:

BIB_HARDWARESPRITE

If set, the card supports hardware sprites. This implies that the sprite support functions in the BoardInfo structure shall be initialized by the card or the chip driver.

BIB_NOMEMORYMODEMIX

Obsolete.

BIB_NEEDSALIGNMENT

Reserved, do not set.

BIB_CACHEMODECHANGE

If set, and the CPU caching mode of the VGA memory region is cache-inhibited, the caching mode of the board memory is set to non-serialised (040) or imprecise (060). This is an optimization setting the user can disable with the DoNoSetMMU environment variable. If this bit is set, then MemorySpaceBase and MemorySpaceSize shall be initialized.

Note that the aim of this bit is not to setup proper caching of video RAM. The CPU libraries perform this step upfront. This flag indicates the opportunity to improve cache mode settings for cards whose memory address range does not include any memory mapped registers.

BIB_VBLANKINTERRUPT

If set, the board can cause a hardware interrupt. If set, the SetInterrupt() function pointer shall be initialized as well. The rtg.library uses this function to enable or disable the interrupt as needed. The card or the chip driver may use the HardInterrupt member of the BoardInfo structure to represent this interrupt and register it as interrupt server through Exec. Except for the is_Code member, the interrupt structure is already initialized and ready for use. The interrupt handler shall identify the source of the interrupt, and if a vertical retrace interrupt is detected, shall create a the software interrupt in BoardInfo->SoftInterrupt through the Cause() function of Exec. The hardware interrupt may be continuous or one-shot, i.e. it is acceptable for the interrupt handler to disable the interrupt once it has been received. The rtg.library will re-enable the interrupt when needed again.

BIB_HASSPRITEBUFFER

If set, the chip or card driver reserved two additional backing store buffers in the video RAM keeping image data overwritten by the soft sprite. Each buffer has a size of (MAXSPRITEWIDTH * MAXSPRITEHEIGHT * 4). bi->MouseSaveBuffer shall be initialized to one of the buffers, bi->MouseImageBuffer to the other buffer. The first keeps the backing store, the other keeps the sprite image converted to the RGB format of the screen the sprite will be rendered into.

BIB_DBLSCANDBLSPRITEY

If set, then the vertical position of the hardware sprite as indicated in the chip registers is counted in single-line modes even if the chip is configured to scan-doubling. That is, the sprite position and sprite resolution is independent from scan-doubling. This may happen, for example, if the sprite is generated by the RAMDAC and not by the VGA chip itself.

BIB_ILACEHALFSPRITEY

If set, then the vertical position of the hardware sprite as indicated in the chip registers is in progressive lines and unaffected by a potentially activated interlace mode. That is, the sprite position and sprite resolution is independent from interlacing. This may happen, for example, if the sprite is generated by the RAMDAC and not by the VGA chip itself.

BIB_DBLCLOCKHALFSPRITEX

If set, then the horizontal position of the hardware sprite is halfed on double-clocked rates. That is, the horizontal sprite position depends on the regular clock, not on the doubled clock.

BIB_ILACEDBLROWOFFSET

If set, then the row offset is computed between lines of the same field in interlace mode. That is, the row offset is computed such that every other line, namely the lines of the corresponding other field, are skipped. Currently, only the Tseng VGA chipset computes row offsets in this particular way. As the rtg.library does not make use of this bit, and programming the row offset is only a matter of the chip driver itself, this flag should be considered obsolete.

BIB_INTERNALMODESONLY

If this bit is set, the rtg.library will not add user display modes to the display info database or display modes created by P96 itself. This is useful for chipsets that cannot generate arbitrary timings, or that generate timings and display resolutions based on some external source.

BIB_FLICKERFIXER

If this bit is set, then the card is equipped with a flicker fixer that is interfaced as a "special feature". This holds for example for the Picasso IV board.

BIB_VIDEOCAPTURE

If this bit is set, the card provides a "special feature" that allows to capture video from some external source.

BIB_VIDEOWINDOW

If this bit is set, the card provides a "special feature" that allows an overlay that displays a fixed memory region, for example to realize a video overlay. In this overlay, the chip may offer color spaces such as YUV in 422 or 420 subsampled mode.

BIB_BLITTER

If this bit is set, the chip offers 2D hardware acceleration. At least the WaitBlitter() function and a subset of the 2D acceleration functions of the BoardInfo structure shall be initialized by the chip or the card driver. Accelerated operations may include copying or inversion of rectangles, filling rectangles with patterns, conversion of planar bitmaps to another RGB format, of rendering of planar data with a user-defined draw-mode. If this bit is set, the rtg.library will also store non-visible bitmaps on the board to make them accessible to the on-chip 2D accelerator (aka "blitter"), assuming that these on-chip operations are faster than the operations performed by the host CPU.

BIB_VGASCREENSPLIT

This bit shall be set if the board allows screen splitting, typically by the VGA line compare register. If so, the rtg.library will allow screen dragging, and will call the SetSplitPosition() to indicate where the topmost line of the bottom screen shall be placed. This bit is new in V45 (3.0) of the rtg.library.

BIB_PALETTESWITCH

This bit shall be set if the board supports dual palette support. This is an unusual non-VGA feature that allows to switch the palette of 8-bit chunky or 4-bit planar modes mid-screen. The first palette populates entries 0 to 255 and displayed at the top of the screen. As soon as the screen-split position is triggered, the graphics hardware switches to the second palette which shall be loaded into the index values 256 to 511. This allows to display two chunky or planar screens at the same time without false colors.

BIB_DACSWITCH

This bit shall be set if the board supports mid-screen DAC mode switching. This is a feature some VGA cards offer as an extension. If present, P96 tries to determine compatible modes by the GetCompatibleDACFormats and their layout by CoerceMode. It allows P96 to allow screen dragging even if the two screens on the monitor have different RGB formats.

The following bits are set by the rtg.library and its callers, and signal settings that are passed into the chip or card driver:

BIB_HIRESSPRITE

The rtg.library sets this bit to request a high-resolution sprite of a width of 64 pixels. If this bit is reset, the hardware sprite is only 32 pixels wide. In either mode, the sprite is as high as wide, and offers 4 user selectable colors, one of them being transparent. Depending on chip restrictions, one of the colors may invert the background. This bit is set according to the flags of the system sprite, and is under control of the Pointer Preferences program on AGA machines.

BIB_BIGSPRITE

The rtg.library sets this bit to stretch the sprite in both horizontal and vertical direction by a factor of 2. This bit is mutually exclusive to BIB_HIRESSPRITE. This bit corresponds to the "BIGSPRITE" ToolType of the Monitor icon.

BIB_BORDEROVERRIDE

If this bit is set, the current border blanking setting is coming from BIF_BORDERBLANK and not from a copy of the corresponding flag in the graphics library ViewPort. The border transparency flag, already selected according to these two inputs, is passed into the SetGC() function pointer of the BoardInfo structure.

BIB_BORDERBLANK

Reflects a user requested state of the border blanking flag. If set, the border is blanked instead of showing overscan data or the background color. Whether this flag or the flag of the graphics.library ViewPort is used to control the border blanking depends on BIB_BORDEROVERRIDE. This bit corresponds to the "BORDERBLANK" ToolType of the monitor icon. If the ToolType is present, BIB_BORDEROVERRIDE is set to override the border blank setting of the graphics.library.

BIB_INDISPLAYCHAIN

If this bit is set, the card includes a VGA switch, and another video signal is routed to the input of the VGA switch. The rtg.library then enables the switch if a video signal from this board is to be shown, and disables the switch for all other video sources, for example the native Amiga video output. If this bit is cleared, the switch is always active and the video signal on the output of this board is always coming from the VGA chip on the board. The video input connector remains then unused. This bit corresponds to the "DISPLAYCHAIN" ToolType of the Monitor icon.

BIB_QUIET

This bit is currently not used by the rtg.library, but corresponds to the "QUIET" ToolType in the Monitor icon, which is honored by the Monitor executable that starts up P96. If set, the card and chip driver should use it to suppress diagnostic messages.

BIB_NOMASKBLITS

If this bit is set, the rtg.library may ignore the Mask value of the RastPort for blitting data, and the chip and card drivers may also ignore the mask when performing bits, i.e. may proceed as if the mask is all-set. Ignoring the mask may speed up blitting, in particular scrolling in text editors or in the Amiga console. While masked blits may improve the performance of the native Amiga chipset, their proper emulation on VGA chipsets may be troubletrouble and non-efficient and thus can be bypassed by if this bit is set. This bit corresponds to the "IGNOREMASK" ToolType of the monitor icon.

BIB_NOP2CBLITS

(or BIB_NOC2PBLITS as incorrectly written in old includes)

If set, the rtg.library uses the CPU to convert planar data to chunky instead of going through the BoardInfo BlitPlanar2Chunky() or BlitPlanar2Direct() functions. As this bit is handled by the rtg.library itself, chip and card drivers may safely ignore it. This bit corresponds to the "NOPLANAR2CHUNKYBLITS" ToolType of the Monitor icon.

BIB_NOBLITTER

If set, the rtg.library disables all 2D acceleration functions and performs all blitting through the host CPU. This bit is handled by the rtg.library itself, and the chip or card driver may safely ignore it. This bit corresponds to the "NOBLITTER" ToolType of the Monitor icon.

BIB_SYSTEM2SCREENBLITS

If set, the chip or card driver may perform system to screen blits, i.e. data written to screen memory with CPU suppoed data as blitter source. Such operations are useful for color expansion. Otherwise, the data should be first written to board memory first, then performing the blit with a memory source. System to screen blits are known to cause problems on some systems where the board takes too logn to end the bus cycle, causing transfers to be lost. This happens for example on some A2000 systems, This bit corresponds to the "SYSTEM2SCREENBLITS" ToolType of the Monitor icon.

BIB_GRANTDIRECTACCESS

If this bit is set, then the card and chip drivers shall be configured such that the CPU can access all VGA memory at any time without having to call SetMemoryMode() of the BoardInfo structure. That is, all RGBFormats modes the board signals as supported shall coexist on the board at all times. That is, if the board supports multiple apperture settings that cannot coexist at the same time, the GetCompatibleFormats() function shall return only those formats that can coexist with the given argument without switching the apperature. This bit may also be set by the chip or card driver itself to signal that all of its RGBFormats may coexist on the Video RAM at the same time. This bit corresponds to the "GRANTDIRECTACCESS" ToolType of the Monitor icon.

BIB_OVERCLOCK

If this bit is set, then also pixel clocks shall be made available that exceed the specified ratings of the hardware. For example, with this bit set, the Cirrus based drivers allow a 10Mhz overclocking. This bit corresponds to the "OVERCLOCK" ToolTypes of the Monitor icon.

SoftSpriteFlags

This bitmask identifies all RGBFormats which do not allow a hardware sprite. The rtg.library will use a soft sprite in such modes instead. For example, the CirrusGD542X can not use the hardware sprite in the TrueColor mode. To indicate this problem, the SoftSpriteFlags are binary or'ed with RGBFF_B8G8R8. From v41 on, the rtg.library provides a more sophisticated method to signal the availability of the hardware sprite. If the EnableSoftSprite() function in the BoardInfo structure returns non-zero, the soft sprite is enabled. The default implementation of this function tests the RGBFormat argument of this function against the SoftSpriteFlags member of the BoardInfo to make this decision and to provide backwards compatibility.

RGBFormats

This bitmask identifies all RGBFormats the chip and card drivers are able to support. It is a binary-OR of RGBFormat flags defined in the BoardInfo.h file. For example, the CirrusGD542X driver supports the following modes, and thus uses the following RGBFormat flags: RGBFF_PLANAR|RGBFF_CHUNKY|RGBFF_B8G8R8|RGBFF_R5G6B5PC|RGBFF_R5G5B5PC

MaxHorValue and MaxVerValue

These two arrays are indexed by the RGBFormat; each entry of the arrays defines the maximum horizontal and vertical values the timing registers of the chip is able to support. These registers define the number of visible pixels on the screen. The actual on-screen bitmap may be wider or smaller, in which case P96 will pan it. The values here limit for example "CRTC_HorizontalTotal", a legacy VGA register.

MaxHorResolution and MaxVerResolution

These two arrays are indexed by the RGBFormat; each entry defines the maximal width or height of an on-screen bitmap in the corresponding mode. Note that these dimensions may be larger than the actual maximal screen dimension; the numbers here rather define the maximal bitmap dimensions the chip can address. For example, even if the screen size is limited to 640x480 pixels, this screen may pan over a 2048x2048 bitmap. The maximal resolution would then be at least 2048, while the actual screen size could be much smaller. The resolutions limit for example "CRTC_RowOffset".

PixelClockCount

This is an array indexed by the RGBFormat that contains for each format the number of different pixel clocks the chip supports.

Functions

If not noted otherwise, registers d0/d1/a0/a1 are scratch registers and may be overwritten by the corresponding function.

AllocCardMem

Synopsis	AllocCardMem(bi, size, force, system);
Inputs	a0	struct BoardInfo *bi
	d0	ULONG size
	d1.w	BOOL force
	d2.w	BOOL system
Result	d0	APTR memorychunk

This function allocates a chunk of graphics board memory from the available free board memory and returns a pointer to the allocated chunk.

If the "force" flag is set, this function may migrate other bitmaps from the board memory to system memory.

If the "system" flag is set, bitmap migration may even include currently visible bitmaps.

It is not advisable to replace this function by a custom implementation.

FreeCardMem

Synopsis	FreeCardMem(bi, membase);
Inputs	a0	struct BoardInfo *bi
Inputs	a1	APTR membase

This function releases a chunk of graphics board memory. The memory size is not available to the function and thus has to be administrated otherwise. It is not advisable to replace this function by a custom implementation.

AllocCardMemAbs

Synopsis	AllocCardMemAbs(bi, size, membase);
Inputs	a0	struct BoardInfo *bi
	d0	ULONG size
	a1	APTR membase

This function attempts to allocate a particular chunk of memory on the board by giving its address and size. If any other allocations are in the way, the allocator attempts to release or move them away to make room for the requested graphics memory block, i.e. the allocation has similar priorities as AllocCardMem() with the system and force flags both set to TRUE.

This function is used, in particular, to allocate memory at the base address of the graphics memory to implement screen dragging.

Memory allocated this way is released through FreeCardMem(). If you do not provide this function, but a custom AllocCardMem(), the rtg.library will disable AllocCardMemAbs(), and hence screen dragging will not be available. This function is new in V42 (3.0) of the rtg.library.

In general, it is not advisable to replace this function.

ReInitMemory

Synopsis	ReInitMemory(bi,RGBFormat);
Inputs	a0	struct BoardInfo *bi
Inputs	d0	RGBFTYPE RGBFormat

This function releases all currently active memory regions and re-initializes the board memory pool for an RGBType that is given by its argument. The library calls this function whenever the RGBFormat is changed to a mode that is incompatible to the RGBFormat currently loaded and, due to changed apperature settings, the currently allocated graphics data needs to be migrated to an off-board memory location.

A typical use case for this function is switching the board to or from a planar mode. Due to the legacy VGA logic, accessing memory in a planar mode re-shuffles the bits as seen by the CPU due to a modification in the apperture mapping of the VGA chip. At the same time, less than the total amount of memory (typically 256K) remains available in planar mode.

The default implementation releases all memory, and then re-initializes the memory pool to a size of MemorySize bytes for all chunky modes or MaxPlanarMemory bytes for the planar mode.

The actual modification of the VGA memory apperture is performed by SetMemoryMode(), not by this function. This function only adjusts the memory pool to the new apperture.

This function is new in V42 (3.0) of the rtg.library.

SetSwitch

Synopsis	SetSwitch(bi, state);
Inputs	a0	struct BoardInfo *bi
Inputs	d0.w	BOOL state
Result	d0.w	BOOL oldstate

This function controls an on-board video switch. If the argument in d0 is 0, the signal on the external video input is switched to the output of the board, and the board video signal becomes unavailable.

If the argument in d0 is 1, the video signal of the on-board VGA chip is routed to the output of the board.

It is advisable to buffer the state to avoid unnecessary switching. The MoniSwitch member of the BoardInfo structure is reserved for the card driver for this purpose.

If the board does not provide a VGA switch, reset the "BIB_INDISPLAYCHAIN" bit in the Flags member of the BoardInfo structure. This function is then not needed, and can be replaced by a dummy that returns directly to the caller.

SetColorArray

Synopsis	SetColorArray(bi, startindex, count);
Inputs	a0	struct BoardInfo *bi
	d0.w	UWORD startindex
	d1.w	UWORD count

This function shall copy "count" values from the CLUT member of the BoardInfo structure starting at "startindex" into the palette of the chip.

Palette values in the BoardInfo structure are always encoded by 8 bits per entry and use the full range from 0 to 255. If the hardware palette uses a bit precision different from 8, this function shall adjust them accordingly, for example by left- or right shifting the entries of the CLUT array before writing them into the hardware registers.

If the BIB_PALETTESWITCH bit is set, this is an indication that the graphics hardware supports two palettes. The first one is loaded into entries 0 to 255 and is shown at the top of the screen. As soon as the screen split position is reached, screen colors will come from the secondary palette which is loaded into entries 256 to 511. That is, if BIB_PALETTESWITCH is set, the startindex argument of the SetColorArray() function may also take values between 256 and 511 which shall then populate entries in the secondary palette.

SetDAC

Synopsis	SetDAC(bi, RGBFormat);
Inputs	a0	struct BoardInfo *bi
Inputs	d0	UWORD region^*
d7	RGBFTYPE RGBFormat

^* This register is not filled in prior release 3.3.0 of P96. Implementations need to check the version of the rtg.library to ensure that they can rely on register d0 being populated correctly.

This function shall reprogram the hardware to display video data according to the RGBFormat passed in in register d7.

If the card driver sets the BIB_DACSWITCH bit to indicate that the graphics card supports mid-screen mode switching, then d0 is also filled in and provides the information to which part of the screen the DAC mode applies to. If d0 is 0, then the DAC mode applies to the entire screen, or the part of the screen above the screen-split position. If d0 is 1, then the DAC mode applies to the lower part of the screen below the screen split position. If screen split is active, P96 calls this function first with d0=0 for the upper, and then with d0=1 for the lower screen region.

Typically, this will reprogram the RAMDAC, e.g. change its settings from chunky to true color.

SetGC

Synopsis	SetGC(bi, mi, border);
Inputs	a0	struct BoardInfo *bi
	a1	struct ModeInfo *mi
	d0	BOOL border

This function shall reprogram the hardware to display video data according to the video mode encoded in the ModeInfo structure, and shall adjust the border blank according to the value in d0. This value shall also be copied into bi->Border. Also, the ModeInfo structure may potentially be modified to reflect the requirements of the mode, e.g. mi->Flags may be adjusted.

Typically, this will reprogram the CRTC and TS (sequencer) registers of a VGA chip to generate the timing for the requested mode. The RAMDAC should not be touched, but will be reprogrammed by SetDAC().

The start address of the bitmap to be displayed will be neither installed by this function, but by SetPanning()

SetPanning

Synopsis	SetPanning(bi, Memory, Width, Height, XOffset, YOffset, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	a1	UBYTE *Memory
	d0	UWORD Width
	d4	UWORD Height^*
	d1	WORD XOffset
	d2	WORD YOffset
	d7	RGBFTYPE RGBFormat

^* The height parameter is not present prior releases 3.3.1. Drivers should not depend on it prior version 44 of the rtg.library. The driver may learn from width, height and the ModeInfo pointer in the BoardInfo structure whether panning is required. Some chips, most notably the INMOS G300 and G364, may require this information.

This function shall set the view origin of a display. In particular, if the screen is panning, this function is used to adjust the pan position. Register a1 contains the start address of the screen bitmap as an Amiga memory address. To get the address relative to the start of the board memory as seen by the VGA chip, bi->MemoryBase must be subtracted.

In order to properly support sprite positioning, this function shall copy the XOffset and YOffset arguments in d1 and d2 to bi->XOffset and bi->YOffset.

These arguments contain the pixel offset of the top left edge of the visible screen relative to the start of the screen. From these offsets and the base address, this function shall compute the linear start address within the board memory, and the values of the panning registers of the VGA chip.

Note that in a split screen setup, only the background screen on top of the monitor can be panned. Thus, this function applies only to the back screen, or to the only screen shown on the monitor. Thus, the RGBFormat is the format of the background screen, or region 0.

The screen width of the front screen is always identical to its mode width as P96 disables screen splitting for autoscroll screens.

CalculateBytesPerRow

Synopsis	CalculateBytesPerRow(bi, Width, Height, mi, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	d0	UWORD Width
	d1	UWORD height^*
	a1	struct ModeInfo mi^*
	d7	RGBFTYPE RGBFormat
Result	d0	UWORD Count

^* The height parameter is not provided prior P96 release 3.3.1. Drivers shall not depends on it if the version of the rtg.library is below 44.

^** The mi (ModeInfo) parameter is not provided prior P96 release 3.3.1. Drivers shall not depend on it if the version of the rtg.library is below 44.

This function shall calculate the byte offset from one line to another line of a bitmap of the indicated pixel width. Thus, it computes the number of bytes a single line of a bitmap of the pixel width in d0 occupies, and for the RGBFormat in d7.

The rtg.library uses this function to compute the size of the required memory for bitmap allocation.

If a bitmap of the given dimension cannot be realized, even by rounding the width up, the function shall return 0.

Some chips, for example the S3Trio, do not support blitting of arbitrary sized bitmaps, and therefore rounds bitmap sizes up to the next supported width.

For some chips, more severe restrictions apply for displayable bitmaps than for off-screen bitmaps. P96 3.3.1 and above therefore provides in register a1 a pointer to the ModeInfo structure describing the mode for which a bitmap is to be constructed. If this pointer is NULL, a non-displayable off-screen bitmap is constructed and the mode information is not relevant. Otherwise, the ModeInfo describes the visible size of the bitmap on the screen, whereas its width and height the total number of pixels in the bitmap. If the dimensions in the arguments and of the ModeInfo differ, the driver shall be prepared that panning will become necessary. Note that this parameter is not provided prior P96 3.3.1 and thus drivers shall test the version number of the rtg.library if they intend to make use of it. Versions 44 and up deliver it.

The height, in register d1, is also only supplied for P96 releases 3.3.1 and on. It may provide, along with the ModeInfo in register a1, sufficient information to understand whether an on-screen bitmap is supposed to be panned. For some chips, more severe restrictions apply if panning is required. In particular, the INMOS chips G300 and G364 fall into this class. Note that a driver should check the version of the rtg.library to learn whether it can depend on this register. Versions 44 and up provide it.

CalculateMemory

Synopsis	CalculateMemory(bi, Memory, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	a1	UBYTE *Memory
	d7	RGBFTYPE RGBFormat
Result	d0	UBYTE *Address

This function shall transform a logical address in the 68K memory map to a physical address, also in the 68K memory map.

While the two addresses are typically identical, they may be different if the chip supports multiple apperture windows that implement byte or word swapping. In such a case, this function transforms the address relative to the logical start address of the VGA memory to an address in the apperature window that is suitable for the RGBFormat in register d7.

GetCompatibleFormats

Synopsis	GetCompatibleFormats(bi, RGBFormat);
Inputs	a0	struct BoardInfo *bi
Inputs	d7	RGBFTYPE RGBFormat
Result	d0	ULONG mask of formats

This function shall return a LONG word bitmask that identifies all RGBFormats that can coexist on the board configured to the RGBFormat passed in without performing an aperture window reconfiguration through SetMemoryMode(). Note that the return value is a bitmask, though the RGBFormat passed in is a bit number.

Note that P96 from release 3.2.0 and up will no longer attempt to migrate bitmaps off board if the aperture window settings change. Instead, it assumes that the VGA memory contents as seen from the graphics chip will stay intact upon an aperture switch. P96 will instead adjust the aperture to the value required by the bitmap to be worked on by the 68K side on the fly, while working on the bitmaps. Instead, 3.2.0 and above will only migrate bitmaps when switching between planar and chunky formats.

Earlier releases migrated bitmaps using RGBFormats not compatible to the intended aperture setting, where incompatibility is identified by this function.

GetCompatibleDACFormats

Synopsis	GetCompatibleDACFormats(bi, RGBFormat);
Inputs	a0	struct BoardInfo *bi
Inputs	d7	RGBFTYPE RGBFormat
Result	d0	ULONG mask of formats

This function shall be present if the BIB_DACSWITCH flag is set in boardinfo->Flags. It shall return a LONG word bitmask that identifies all RGBFormats that can be displayed along with the RGB format passed in on a split screen. Note that the return value is a bitmask, though the RGBFormat passed in is a bit number.

When preparing a split screen display, and BIB_DACSWITCH is set, then P96 uses this function to determine which RGB modes can be shared on the screen, and between which the board can switch mid-screen. P96 furthermore uses the CoerceMode function to determine the characteristics of the mode of the background screen.

Note that this function is very different from GetCompatibleFormats: The latter indicates RGB modes that can be read and modified simultaneously in video RAM without requiring an aperture switch, whereas this function indicates RGB modes that can be shown on the screen at the same time. The two bitmasks may be different as the former describes properties of CPU interface to video RAM, whereas this function identifies properties of the RAMDAC.

For example, cards will typically require an aperture switch between big and little endian modes such that GetCompatibleFormats will identify them as non-compatible. However, as endian switching is applied between CPU and video RAM without changing the bit values in video RAM, displaying them on the same screen is typically not a problem.

SetDisplay

Synopsis	SetDisplay(bi, state);
Inputs	a0	struct BoardInfo *bi
Inputs	do	BOOL state

This function shall enable or disables the video output according to the input in register d0. A disabled video output will show no picture, though sync signals shall still be generated.

The rtg.library expects that WaitVerticalSync() is still operational even if the display is disabled.

On VGA chips, this function is typically implemented through bit 5 of the TSMode register of the sequencer.

ResolvePixelClock

Synopsis	ResolvePixelClock(bi, mi, clock, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	a1	struct ModeInfo *mi
	d0	LONG pixelclock
	d7	RGBFTYPE RGBFormat
Result	d0	ULONG index

This function shall convert a pixel clock in Hz to an index in an internal lookup table that can later be used to check for the actual pixel clock. It shall also fill in the Numerator, Denominator and PixelCLock members of the ModeInfo structure passed in. It may also clear GMF_INTERLACE and/or GMF_DOUBLECLOCK flags if the board does not support the corresponding feature, or set GMF_DOUBLECLOCK if a particular pixel clock requires double-clocking. It shall also install the effective pixel clock (in Hz) into mi->PixelClock of the ModeInfo structure.

The information in the ModeInfo structure is later used to adjust the timing of the VGA chip through SetPixelClock.

GetPixelClock

Synopsis	GetPixelClock(bi, mi, index, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	a1	struct ModeInfo *mi
	d0	ULONG index
	d7	RGBFTYPE RGBFormat
Result	d0	ULONG pixelclock

This function shall convert a ModeInfo, an RGBFormat and an index into the internal clock table to a pixel clock in Hz.

Depending on the chip and the RGBFormat, the internal clock table and an index into this table may not be sufficient, and additional arguments are provided to resolve this problem. For example, the Cirrus 542X chips operate in true-color modes at one third of the internal clock.

SetClock

Synopsis	SetClock(bi);
Inputs	a0	struct BoardInfo *bi

This function shall program the pixel clock of the chip according to the mode stored in bi->ModeInfo and, potentially, other settings such as bi->RGBFormat.

This function will typically program the VGA sequencer registers according to the numerator and denominator members of the ModeInfo structure which is currently active in the BoardInfo, namely the mi->Numerator and mi->Denominator members of the ModeInfo structure. This clock information is deposited there by ResolvePixelClock.

SetMemoryMode

Synopsis	SetMemoryMode(bi, RGBFormat);
Inputs	a0	struct BoardInfo *bi
Inputs	d7	RGBFTYPE RGBFormat

This function shall set the aperture settings of the chip according to the RGBFormat passed in.

As such, this function may enable the "chain 4 mode" for chunky or direct color modes, or disable it for planar modes. For chips offering aperature windows, this function may also modify the aperture setting and enable or disable byte or word-swapped modes in one of the aperture windows.

Note that RGBFormats requiring different aperture settings in the same aperture window shall be marked as "incompatible" through GetCompatibleFormats() because data stored in the affected aperature window appears to change under a mode adjustment.

This function shall preserve all registers!

SetWriteMask

Synopsis	SetWriteMask(bi, mask);
Inputs	a0	struct BoardInfo *bi
Inputs	d0	UBYTE mask

This function shall install a write mask through which write accesses to planar bitmaps is routed.

The write mask is a legacy VGA feature that routes write accesses into the VGA memory area to one or multiple of the four VGA memory planes in a planar organization. This function will typically adjust the WritePlaneMask register of the VGA sequencer.

This function is only called for the planar RGBFormat. For all other RGBFormats, writes access the VGA memory directly, or through a potential aperature mapping.

This function shall preserve all registers!

SetClearMask

Synopsis	SetClearMask(bi, mask);
Inputs	a0	struct BoardInfo *bi
Inputs	d0	UBYTE mask

This function shall select which VGA planes are reset on writes to the VGA memory window, regardless of the data written. A one-bit identifies a plane that is cleared upon a write access. It shall also copy the mask into the ClearMask member of the BoardInfo structure.

This function is only called for the planar RGBFormat, it is not used for chunky or direct color modes.

This function would typically install a 0 into the Set/Reset register of the VGA graphics controller, and would copy the mask into the Enable Set/Reset register of the VGA graphics controller.

SetReadPlane

Synopsis	SetReadPlane(bi, plane);
Inputs	a0	struct BoardInfo *bi
Inputs	d0	UBYTE plane

This function shall select which of the four VGA planes is addressed by a read from the VGA memory window. Only bits from the selected plane are returned to the CPU, all other planes are ignored. The data in d0 is a plane index from 0 to 3, not a plane mask.

This function is only used in the planar RGBFormat, not in the chunky or direct RGBFormats.

It would typically install the plane value in d0 into the Read Map Select register of the VGA graphics controller.

Note that the plane argument is a plane number from 0 to 3, it is not a bitmask.

WaitVerticalSync

Synopsis	WaitVerticalSync(bi);
Inputs	a0	struct BoardInfo *bi
Inputs	d0	BOOL end

This function shall wait for the next vertical retrace, even if the display is disabled through SetDisplay().

If "end" is TRUE, the function shall wait for the end of the vertical sync, otherwise it shall wait for the start of the vertical sync.

Note that the latter imposes that it is in the responsibility of this function to ensure that a vertical retrace will happen at some point, even with a disabled display.

NOTE: The primary purpose of this function is to avoid to change some card registers mid-screen, and thus synchronize their change to the vertical blank even in the absence of a hardware interrupt. If no hardware indicator is available whether the start or the end of the vertical blank has been reached, it shall simply wait for the next vertical blank if "end" is FALSE, and do nothing otherwise. If the hardware provides no information on the vertical blank at all, the function should delay the CPU for a while on a best effort basis.

GetVSyncState

Synopsis	GetVSyncState(bi,expected);
Inputs	a0	struct BoardInfo *bi
Inputs	d0	BOOL expected

This function shall return an indicator whether the card is currently in the vertical retrace. If so, the function shall return a value different from 0. If the card is in the active display area, this function shall return 0. P96 may use the return value to short-cut waiting for the next vertical blank if such an operation is requested.

On VGA chips, this function will typically test bit 3 of the INPUTSTATUS1 register which provides the requested information.

If the card cannot supply such information, it is always safe to return the "expected" argument in d0.

SetInterrupt

Synopsis	SetInterrupt(bi, state);
Inputs	a0	struct BoardInfo *bi
Inputs	d0	state

This function shall disable or enable the board interrupts according to its argument in d0. If the board does not generate interrupts, this function does not perform any operation.

The rtg.library disables interrupts during screen switches to avoid problems.

WaitBlitter

Synopsis	WaitBlitter(bi);
Inputs	a0	struct BoardInfo *bi

This function shall wait for the completion of any pending blitter operations.

SetSprite

Synopsis	SetSprite(bi, activate, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	d0	BOOL activate
	d7	RGBFTYPE RGBFormat

This function shall disable or enable the hardware sprite of the board if there is any. If the argument is 0, the sprite shall be disabled, otherwise it shall be enabled.

If the VGA chip does not provide a hardware sprite, this function does nothing.

SetSpritePosition

Synopsis	SetSpritePosition(bi, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	d0	WORD XPos
	d1	WORD YPos
	d7	RGBFTYPE RGBFormat

This function shall set the position of the hardware sprite position from its arguments. To convert the arguments to coordinates relative to the left top of the View, the following arithmetic operations are performed:

sprite_xpos = XPos - bi->XOffset

sprite_ypos = YPos - bi->YOffset + bi->YSplit

This function shall furthermore store its arguments in d0 and d1, without any change, in bi->MouseX and bi->MouseY.

NOTE: For legacy reasons, the rtg.library also stores the function arguments in d0,d1 in bi->MouseX and bi->MouseY before calling this function. This service may, however, be removed in future versions of the rtg.library, and implementations shall not depend on this behavior.

SetSpriteImage

Synopsis	SetSpriteImage(bi, RGBFormat);
Inputs	a0	struct BoardInfo *bi
Inputs	d7	RGBFTYPE RGBFormat

This function shall update the shape of the hardware sprite from the BoardInfo->MouseImage shape. This shape is organized as pairs of 16-bit or 32-bit words, word defining the first plane, and the second word defining the second bitplane.

The sprite size and the sprite resolution shall be selected according to the BIB_HIRESSPRITE and BIB_BIGSPRITE flags in the BoardInfo->Flags member:

Neither BIB_HIRESSPRITE nor BIB_BIGSPRITE are set:

skip the first two 16-bit words. The following data is arranged as an array of pairs of 16-bit words, namely BoardInfo->MouseHeight of them. They form the two bit planes for one line of the sprite, i.e. the sprite is at most 16 pixels wide.

BIB_HIRESSPRITE is set:

skip the first two 32-bit long words. The following data is arranged as an array of pairs of 32-bit long words, namely BoardInfo->MouseHeight of them. They form the two bit planes for one line of the sprite, i.e the sprite is at most 32 pixels wide.

BIB_BIGSPRITE is set:

skip the first two 16-bit words. The following data is arranged as an array of pairs of 16-bit words, each defining a bitplane of one line of the sprite. However, in this case each pixel is twice as wide and twice as high as in the regular case, and this function shall perform all necessary action to scale the the data accordingly. That is, the sprite is at most 32 pixels wide, though the data is upscaled from a 16 pixel wide image. Coordinates for sprite movements are already adjusted, only the sprite image requires scaling.

All other bit combinations are invalid.

SetSpriteColor

Synopsis	SetSpriteColor(bi, index, red, green, blue, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	d0.b	index
	d1.b	red
	d2.b	green
	d3.b	blue
	d7	RGBFTYPE RGBFormat

This function shall change one of the 3 possible colors of the sprite image to the RGB triple passed in. The color index is a value between 0 and 2, the RGB values are 8-bit values. If the sprite colors have a different color precision, this function shall scale the RGB triple accordingly.

Note that some if not most VGA chips only offer 2 selectable sprite colors, namely color 0 and color 2. Color 1 typically inverts the background behind the sprite and cannot be selected.

EnableSoftSprite

Synopsis	EnableSoftSprite(bi,fmtflags,modeinfo);
Inputs	a0	struct BoardInfo *bi
	d0.l	fmtflags
	a1.l	struct ModeInfo *modeinfo

This function shall check whether a software sprite shall be enabled for a particular mode. fmtflags is a bitmask defined from the RGBFormat, i.e. it equals 1<<RGBFormat. The function shall check whether in the format and mode info passed in, the hardware sprite can be displayed. If not so, i.e. if a software sprite is required, the function shall return TRUE. Otherwise, i.e. if a hardware sprite can be used, it shall returns TRUE.

This function is new in rtg.library V41 (2.4.0).

If it is not defined, the rtg.library computes the bitwise AND of the SoftSpriteFlags with the fmtflags and enables the software sprite if the result is non-zero.

This function allows a a finer control of the software sprite than the SoftSpriteFlags.

BlitPlanar2Chunky

Synopsis	BlitPlanar2Chunky(bi, bm, ri, SrcX, SrcY, DstX, DstY, SizeX, SizeY, MinTerm, Mask);
Inputs	a0	struct BoardInfo *bi
	a1	struct BitMap *bm
	a2	struct RenderInfo *ri
	d0.w	SrcX
	d1.w	SrcY
	d2.w	DstX
	d3.w	DstY
	d4.w	SizeX
	d5.w	SizeY
	d6.b	MinTerm
	d7.b	Mask

This function shall blit a planar bitmap anywhere in the 68K address space into a chunky bitmap in video RAM. The source bitmap that contains the data to be blitted is in the bm argument. If one of its plane pointers is 0x0, the source data of that bitplane shall be considered to consist of all-zeros. If one of its plane pointers is 0xffffffff, the data in this bitplane shall be considered to be all ones.

The RenderInfo describes the target memory address in video RAM where the data shall be blitted to. SrcX and SrcY are the offsets into the source bitmap, DstX and DstY the target offset in the video RAM described by the RenderInfo. SizeX and SizeY is the width and height of the rectangle to be blitted.

MinTerm specifies the render operation in the form of an Amiga blitter minterm definition, Mask is a binary mask that identifies which (logical) planes of the target shall be affected.

This function need not to implement all possible parameter combinations. In case it cannot perform an operation through hardware acceleration, it may instead call the BlitPlanar2ChunkyDefault() function of the BoardInfo structure to blit the data by the CPU.

This function likely needs to copy the planar source data to video RAM before attempting the conversion.

FillRect

Synopsis	FillRect(bi, ri, X, Y, Width, Height, Pen, Mask, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	a1	struct RenderInfo *ri
	d0.w	X
	d1.w	Y
	d2.w	Width
	d3.w	Height
	d4.l	Pen
	d5.b	Mask
	d7.l	RGBFormat

This function shall fill a rectangle in the video RAM with a constant color. The RenderInfo structure describes the target area in the video RAM. X and Y are the top-left point of the rectangle to be filled, Width and Height its dimensions in pixels.

Pen is the color with which the rectangle is to be filled. This is an 8-bit value for chunky bitmaps, or a 16, 24, or 32 bit value for direct color modes.

Mask defines which logical planes of a chunky or planar bitmap are to be filled. It can be ignored for direct color modes.

RGBFormat is the format of the target video RAM. This format is not taken by the RenderInfo structure.

This function need not to implement all possible parameter combinations. In case it cannot perform an operation through hardware acceleration, it may instead call the FillRectDefault() function of the BoardInfo structure to fill the rectangle by the CPU.

InvertRect

Synopsis	InvertRect(bi, ri, X, Y, Width, Height, Mask, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	a1	struct RenderInfo *ri
	d0.w	X
	d1.w	Y
	d2.w	Width
	d3.w	Height
	d4.l	Mask
	d7.l	RGBFormat

This function shall invert a rectangular region in the video RAM described by the RenderInfo structure. X and Y are the top left coordinate of the rectangle relative to the RenderInfo, Width and Height its dimension.

Mask is a bitmask that describes which of the logical planes of a chunky or planar bitmap are to be filled. The mask can be ignored for direct color modes.

RGBFormat is the format of the video RAM. This information is not taken from the RenderInfo.

This function need not to implement all possible parameter combinations. In case it cannot perform an operation through hardware acceleration, it may instead call the InvertRectDefault() function of the BoardInfo structure to invert the rectangle by the CPU.

The rtg.library calls this function for some parameter combinations of BltMitMap(), BltPattern() and BltTemplate().

BlitRect

Synopsis	BlitRect(bi, ri, SrcX, SrcY, DstX, DstY, SizeX, SizeY, Mask, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	a1	struct RenderInfo *ri
	d0.w	SrcX
	d1.w	SrcY
	d2.w	DstX
	d3.w	DstY
	d4.w	SizeX
	d5.w	SizeY
	d6.b	Mask
	d7.l	RGBFormat

This function shall copy a rectangular image region in the video RAM. RenderInfo describes the video RAM containing the source and target rectangle, SrcX/SrcY are the top-left edge of the source rectangle, DstX/DstY the top-left edge of the destination rectangle, and SizeX/SizeY the dimensions of the rectangle to copy.

Source and destination rectangle may be overlapping, a proper copy operation shall be performed in either case.

Mask is a bitmask defined by a single byte that defines which (logical) planes are affected by the copy for planar or chunky bitmaps. The driver can ignore the mask direct color modes. (Note that this is not a mask bitplane that defines opacity of pixels, it is a bitmask that identifies affected bitplanes for planar or chunky blits).

RGBFormat is the format of the source (and destination); this format shall not be taken from the RenderInfo.

This function need not to implement all possible parameter combinations. In case it cannot perform an operation through hardware acceleration, it may instead call the BlitRectDefault() function of the BoardInfo structure to copy the rectangle by the CPU.

The rtg.library calls this function to implement some of the parameter combinations of the BltBitMap() function of the graphics.library.

BlitTemplate

Synopsis	BlitTemplate(bi, ri, template, X, Y, Width, Height, Mask, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	a1	struct RenderInfo *ri
	a2	struct Template *template
	d0.w	X
	d1.w	Y
	d2.w	Width
	d3.w	Height
	d4.b	Mask
	d7.l	RGBFormat

This function shall expand a 1-plane deep planar bitplane to a full-color pattern in video RAM. The Template structure defined in <boardinfo.h> describes this bitplane.

template->Memory points to the source of the template which need not to be in video RAM.

template->BytesPerRow defines the byte offset from one line of the template to another, template->Xoffset a pixel offset into the template, which is logically one long strip of data.

template->DrawMode defines in which mode the template shall be drawn; the mode definitions are identical to that of the rastport structure of the graphics library.

template->FgPen and template->BgPen define the foreground and background pen that shall be used for rendering the template.

The X and Y parameters define the top left edge in the video RAM given through the RenderInfo structure at which the template shall be drawn.

Width and Height provide its dimension.

The Mask is a bitmask that defines for planar and chunky modes which logical bitplanes shall be affected by the rendering. It can be ignored for direct color modes.

RGBFormat is the format of the destination video RAM; this information shall not be taken from the RenderInfo structure.

This function may potentially need to copy parts of the template to video RAM before proceeding with its operation.

This function need not to implement all possible parameter combinations. In case it cannot perform an operation through hardware acceleration, it may instead call the BlitTemplateDefault() function of the BoardInfo structure to draw the template by the CPU.

This function is used by the rtg.library to implement some parameter combinations of the graphics.library BltTemplate() function.

BlitPattern

Synopsis	BlitPattern(bi, ri, pattern, X, Y, Width, Height, Mask, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	a1	struct RenderInfo *ri
	a2	struct Pattern *pattern
	d0.w	X
	d1.w	Y
	d2.w	Width
	d3.w	Height
	d4.w	Mask
	d7.l	RGBFormat

This function shall fill a rectangular region in video RAM with a pattern. The pattern consists of a one-bitplane deep bitmap which shall be expanded repeatedly to fill the entire destination rectangle.

The RenderInfo structure defines the video RAM region within which the rectangle is located to be filled.

The Pattern structure, defined in <boardinfo.h> describes the pattern to be used. Pattern->Memory points to the bitmap containing the pattern as one-bitplane deep binary pattern. This memory may not be within video RAM.

Pattern->XOffset and Pattern->YOffset set the start position within the pattern which shall be placed at the left-top edge of the destination rectangle, i.e. the pattern is shifted Pattern->XOffset to the left and Pattern->YOffset to the top to identify the pixel to be placed at the origin of the destination rectangle.

Pattern->FgPen and Pattern->BgPen are the foreground and background pen that shall be used to draw the pattern, Pattern->DrawMode is the draw mode in the form of a graphics.library rastport draw mode.

The pattern is always 16 pixels (one word) wide, and consists of 1<<Pattern->Size lines. That is, the size is given as exponent to the base of 2, not directly as height in pixels.

X and Y are the top left edge of the rectangle to be filled with the pattern.

Width and Height are the dimensions of the rectangle to be filled.

Mask is a bitmask that identifies which of the logical planes of a chunky or planar video RAM region shall be affected. It can be ignored for direct color modes.

RGBFormat is the format of the video RAM; this format shall not be taken from the RenderInfo structure.

This function may potentially need to copy parts of the template to video RAM before proceeding with its operation.

This function need not to implement all possible parameter combinations. In case it cannot perform an operation through hardware acceleration, it may instead call the BlitPatternDefault() function of the BoardInfo structure to draw the template by the CPU.

This function is used by the rtg.library to implement some parameter combinations of the graphics.library BltPattern() function. In particular, it is only used for single-color patterns, i.e. if AreaPtSz is positive. Multi-color patterns are filled by the CPU, or through combinations of this or other acceleration primitives.

DrawLine

Synopsis	DrawLine(bi, ri, line, Mask, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	a1	struct RenderInfo *ri
	a2	struct Line *line
	d0.b	Mask
	d7.l	RGBFormat

This function shall draw a line in a video RAM region described by the RenderInfo structure.

The line itself is given by the Line structure defined in <boardinfo.h>. Note that lines are potentially clipped at window boundaries, or partially overlapped window bounds. Thus, a line may be drawn in multiple segments. The line structure contains information on both the entire line, as well as the line segment to be drawn. This is necessary to ensure pixel-precise clipping such that a partially obscured line fits together again when an overlapping window is moved away later.

Line->X and Line->Y are the starting coordinate of the line segment to be drawn, in coordinates relative to the origin of the RenderInfo. Line->Length is the length of the line segment to be drawn in pixels. This is also the maximum of the horizontal and vertical extent of the line segment to be drawn.

Line->dX and Line->dY contain the coordinate difference between the end position minus the start position of the entire line, and not just the line segment.

Line->sDelta and Line->lDelta contain the maximum and minimum line extend, including the sign bit. That is, if abs(Line->dX) is larger than abs(Line->dY), with abs(x) the absolute value of x, then Line->lDelta contains Line->dX, and Line->sDelta contains Line->dY. Otherwise, Line->lDelta contains Line->dY, and Line->sDelta contains Line->dX.

Line->twoSDminusLD contains the value of the Bresenham "work variable" at the start of the line segment, not the entire line. This work-variable allows the algorithm to decide in which direction the next pixel is to be drawn, and to continue a clipped line by another line segment.

Line->LinePtrn is a bitmask that defines which dots of the line are drawn in the JAM1 mode, or which are drawn in the foreground and which are drawn in the background pen in JAM2 mode. 1-bits identify foreground pixels. The draw mode of the line is in Line->DrawMode in the same encoding as used by the rastport structure of the graphics.library.

Line->PatternShift selects which bit of the pattern is to be used for the origin of the line and thus shifts the pattern to the indicated number of bits to the left. It is the pattern shift value at the start of the line segment to be drawn.

Line->FgPen and Line->BgPen define the foreground and background pens in which the line shall be drawn.

Line->Horizontal defines the major and minor draw direction of the line. If this member is non-zero, the major draw direction is horizontal, i.e. abs(Line->dX) > abs(Line->dY). Otherwise, the draw direction is vertical.

Line->DrawMode is a copy of the draw mode from the RastPort into which the line shall be drawn (e.g. JAM1, JAM2, INVERSEVID etc.).

Line->Xorigin and Line->Yorigin are the start position of the entire line, not just the line segment.

If a Bresenham algorithm is used to implement the line drawer, the work variable is used as follows: Whenever it is negative, only a step into the major direction is made, where the major direction is defined by Line->Horizontal, and the step orientation is given by the sign of Line->lDelta. If it is non-negative, a step in the major and a step minor direction is made. For each move in the major direction, 2Line->sDelta is added to Line->twoSDminusLD. For move in the minor direction, Line->lDelta is additonally subtracted from it.

Even though only the extend of the line segment in the major direction is provided in Line->Length, the Bresenham work variable allows to compute the (pixel precise) extend of the line in the minor direction. In specific,

sExtend = ((Line->sDelta << 1) * (Line->Length - 1) + Line->lDelta + Line->twoSDminusLD) / (Line->lDelta << 1);

This function need not to implement all possible parameter combinations. In case it cannot perform an operation through hardware acceleration, it may instead call the DrawLineDefault() function of the BoardInfo structure to draw the template by the CPU. If there is no line drawing acceleration offered by the VGA chip, this function pointer may be left unitialized in which case it remains its default value, namely DrawLineDefault().

This function is used by the rtg.library to implement line drawing. However, solid horizontal and vertical lines are instead drawn as slim rectangles to speed up processing and provide acceleration even if the VGA chip does not offer line drawing primitives.

BlitRectNoMaskComplete:

Synopsis	BlitRectNoMaskComplete(bi, sri, dri, SrcX, SrcY, DstX, DstY, SizeX, SizeY, OpCode, RGBFormat);
Inputs	a0	struct BoardInfo *bi
	a1	struct RenderInfo *sri
	a2	struct RenderInfo *dri
	d0.w	SrcX
	d1.w	SrcY
	d2.w	DstX
	d3.w	DstY
	d4.w	SizeX
	d5.w	SizeY
	d6.b	OpCode
	d7.l	RGBFormat

This function shall copy one rectangle in video RAM to another rectangle in video RAM using a mode given in d6. A mask is not applied.

The source region in video RAM is given by the source RenderInfo in a1 and a position within it in SrcX and SrcY.

The destination region in video RAM is given by the destinaton RenderInfo in a2 and a position within it in DstX and DstY.

The dimension of the rectangle to copy is in SizeX and SizeY.

The mode is in register d6, it uses an Amiga style Blitter MinTerms encoding of the graphics.library, but as only two sources (approximately representing the functionality of B and C channels of the Amiga blitter) are supported, only 4 bits are required to encode the minterms. In the following table, B is the source and C the destination:

Bit 3	B ∧ C
Bit 2	B ∧ ¬ C
Bit 1	¬ B ∧ C
Bit 0	¬ B ∧ ¬ C

The minterm is formed by identifying all combinations of source (B) and destination (C) for which the output shall be set, and then setting the corresponding bits of the minterm. For example, to move the source to the destination D, the requested operation is D ← B = (B ∧ C) ∨ (B ∧ ¬ C), thus the minterm is %1100 = 0xc = 12.

The common RGBFormat of source and destination is in register d7, it shall not be taken from the source or destination RenderInfo.

This function need not to implement all possible parameter combinations. In case it cannot perform an operation through hardware acceleration, it may instead call the BlitRectNoMaskCompleteDefault() function of the BoardInfo structure to copy the rectangle by the CPU.

The rtg.library uses this function for some parameter combinations of BltMaskBitMap(), and also to move bitmaps in video RAM as part of the memory management.

BlitPlanar2Direct

Synopsis	BlitPlanar2Direct(bi, bm, ri, cim, SrcX, SrcY, DstX, DstY, SizeX, SizeY, MinTerm, Mask);
Inputs	a0	struct BoardInfo *bi
	a1	struct BitMap *bm
	a2	struct RenderInfo *ri
	a3	struct ColorIndexMapping *cim
	d0.w	SrcX
	d1.w	SrcY
	d2.w	DstX
	d3.w	DstY
	d4.w	SizeX
	d5.w	SizeY
	d6.b	MinTerm
	d7.b	Mask

This function shall convert bitplanes in planar encodings to a region in video RAM using a direct color RGBFormat, i.e. 15 to 32 bit. The source bitmap may not be in video RAM, but can reside anywhere in the 68K memory map.

If a bitplane pointer of the source bitmap is 0x0, the function shall assume that all bits of this bitplane are 0. If a bitplane pointer of the source bitmap is 0xffffffff, the function shall assume that all bits of this bitplane are 1.

The ColorIndexMapping defined in <boardinfo.h> defines to which color values the color pens from the source bitmap are converted to. The cim->ColorMask identifies those bits in the target video RAM which carry color information. Zero-bits in this mask are either not used, or represent opacity information. The actual lookup table that provides per pen value a color value is in cim->Colors. They are words, triple bytes or long words right-padded into 32-bit long words:

RGBFormat	Color Index Mapping (as sequence of bits)
RGBFB_A8B8G8R8	`0000 0000 bbbb bbbb gggg gggg rrrr rrrr`
RGBFB_R8G8B8	`0000 0000 bbbb bbbb gggg gggg rrrr rrrr` (yes, no typo)
RGBFB_A8R8G8B8	`0000 0000 rrrr rrrr gggg gggg bbbb bbbb`
RGBFB_B8G8R8	`0000 0000 rrrr rrrr gggg gggg bbbb bbbb` (yes, no typo)
RGBFB_R8G8B8A8	`rrrr rrrr gggg gggg bbbb bbbb 0000 0000`
RGBFB_B8G8R8A8	`bbbb bbbb gggg gggg rrrr rrrr 0000 0000`
RGBFB_R5G6B5PC	`0000 0000 0000 0000 gggb bbbb rrrr rggg`
RGBFB_R5G5B5PC	`0000 0000 0000 0000 gggb bbbb 0rrr rrgg`
RGBFB_R5G5B5	`0000 0000 0000 0000 0rrr rrgg gggb bbbb`
RGBFB_R5G5B5	`0000 0000 0000 0000 rrrr rggg gggb bbbb`
RGBFB_B5G6R5PC	`0000 0000 0000 0000 gggr rrrr bbbb bggg`
RGBFB_B5G5R5PC	`0000 0000 0000 0000 gggr rrrr 0bbb bbgg`

SrcX and SrcY specify the left top edge of the rectangle in the source bitmap to be converted.

DstX and DstY specify the left top edge of the rectangle in the video RAM region in the RenderInfo.

MinTerm encodes the operation that is to be performed on the rectangle, its interpretation follows the MinTerms definition of the graphics.library, except that only two sources are combined by the minterm, approximately corresponding to the Amiga blitter channels B and C. The minterm definitions follow those used in BlitRectNoMaskComplete(). However, since a color map is involved, the function may be non-obvious, and the following table lists the intended function by MinTerm. The term "B" corresponds to the pixel value extracted from the planar source bitmap, the term CIM to the color map, and the term "C" to the value of the (hi- or true-color) destination. This corresponds approximately to how the Amiga blitter channels would be assigned. The symbol ¬ represents inversion of all color-carrying bits. The stencil bit of the 15-bit hi-color format and the alpha value of the 32-bit true-alpha pixels are not affected by it. If applied on the planar source data B, it inverts all bits included in the mask and leaves bits unchanged which are reset in the mask.

MinTerm	Value of the Destination
0	CIM[0]
3	CIM[¬ B]
5	¬ C
10	C (target remains untouched)
12	CIM[B]
15	CIM[¬ 0]

All other minterms are not passed into the driver and handled by the rtg.library internally.

Mask is a bitmask that identifies which of the source bitplanes shall be considered for the conversion and for the inversion through ¬.

This function likely needs to copy the planar source data to video RAM before attempting the conversion.

This function need not to implement all possible parameter combinations. In case it cannot perform an operation through hardware acceleration, it may instead call the BlitPlanar2DirectDefault() function of the BoardInfo structure to blit the data by the CPU.

SetSplitPosition

Synopsis	SetSplitPosition(bi,ypos);
Inputs	a0	struct BoardInfo *bi
Inputs	d0	UWORD ypos

This function shall sets the vertical position at which the screen is split. That is, if the line number given by the second argument is reached, the raster pointer shall be reset to address 0 relative to the start of the video RAM.

An argument of 0 indicates that screen splitting shall be disabled.

In order to support proper sprite positioning, the function shall store its ypos argument in bi->YSplit.

The rtg.library arranges the screen such that the screen that appears in the background and thus at the top of the monitor is started at the memory computed by SetPanning(), and the frontmost (dragged) screen starts at address 0. In particular, it ensures that the dragged screen does not pan and uses the same (or, since 3.3.0, a compatible) RGBFormat than the background screen. This function is used to implement screen dragging. It is only called if the BIB_VGASCREENSPLIT flag in BoardInfo->Flags is set. This function is new in version 42 (3.0) of the rtg.library.

CoerceMode

Synopsis	CoerceMode(bi,coerced,backmode,backrgb,frontrgb,backwidth,frontwidth);
Inputs	a0	struct BoardInfo *bi
	a1	struct ModeInfo *coerced
	a2	const struct ModeInfo *backmode
	d0	RGBFMODE backrgb
	d1	RGBFMODE frontrgb
	d2	UWORD backwidth
	d3	UWORD frontwidth

This function shall be present if the BIB_DACSWITCH is set in boardinfo->Flags. It is used to compute the layout of a coerced mode in a split-screen arrangement of two different RGBFormats sharing the same monitor.

In such a setup, the frontmost (dragged) screen is always showin in its original, intended RGBFormat with its intended dimensions, but the background mode may appear in an altered, "coerced" mode due to restrictions of the chipset. Such coercion may change the aspect ratio of the pixels, and by that also the size of the visible screen.

The mode information in 'coerced' pointed to by register a1 is, upon entry of this function, the mode information belonging to the frontmost (dragged) screen. Upon exit, this structure shall be updated to describe the mode of the back (coerced) screen, and the register d0 shall contain the common line width of both screens.

The mode information in 'backmode' pointed to by register a2 contains the original, intended mode for the background screen, used as a basis for computing the coerced mode. It shall not be modified by this function.

The backrgb argument in register d0 contains the intended RGB mode of the background screen, the frontrgb mode in register d1 contains the RGB mode of the frontmost (dragged) screen.

While the mode information contains the nominal extend of these modes, i.e. how many pixels of a particular mode fit to the monitor, the actual screen dimensions may alter from the mode dimensions. If that happens, P96 and intution allow the user to pan the screen on the monitor.

The value d2 contains the width, in pixels, of the background screen that is to be coerced, the value d3 the width of the screen of the frontmost (dragged) screen.

This function shall perform the following computations:

First, it shall compute a common width, suitable for being loaded into the VGA panning register, of both screens, measured in pixels of the coerced (background) screen. This value is returned in register d0. Note that most VGA chipses only offer one register to hold the number of bytes per line, and for that, this function needs to find a common pixel count that suits the coerced and the dragged screen. It shall return 0 if coercion is not possible.

Second, it shall update the mode information pointed to by 'coerced' and passed into register a1 to properly describe the properties of the coerced background mode. In particular, if the pixel dimensions of the coerced mode differ from the intended mode because the DAC cannot create pixels of the dimension of the intended mode, the width of the mode needs to be adjusted such that it represents the number of visible pixels correctly.

For example, the following algorithm describes mode coercion on a setup where coercion of a high-color (background) screen to a chunky (dragged) screen doubles the horizontal pixel widths due to different clock ratios:

The mode width of the mode information in a1 is halfed, indicating that only half as many pixels as for the chunky dragged screen fit on the screen,
The screen width in register d2 is multiplied by 2 as every high-color pixel takes two bytes
The function computes the maximum of d3, the pixel count and by that also the byte count of the frontmost (dragged) screen and d2, the (computed) byte count of the background (coerced) screen, and...
the resulting byte count is divided by two, to give a pixel count as the coerced mode is a high-color mode requiring two bytes per pixel. The result of this computation is passed out.

Taking the maximum ensures that both the dragged and the coerced screen can be shown simultaneously, and share a common bytes per line count, as required by most VGA chipsets.

ResetChip

Synopsis	ResetChip(bi);
Inputs	a0	struct BoardInfo *bi

This function shall re-initialize the chip for P96 after a client requested direct access to the hardware registers.

This function is reserved and is currently not in use.

SetDPMSLevel

Synopsis	SetDPMSLevel(bi, DPMSLevel);
Inputs	a0	struct BoardInfo *bi
Inputs	d0	ULONG DPMSLevel

This function shall set the DPMS (monitor power savings) level supplied.

The DPMSLevel argument is one of the following (see <boardinfo.h>):

DPMS_ON (normal operation),
DPMS_STANDBY (Optional state of minimal power reduction),
DPMS_SUSPEND (Significant reduction of power consumption),
DPMS_OFF (Monitor off, lowest level of power consumption)

GetFeatureAttrs

Synopsis	GetFeatureAttrs(bi, featuredata, type, tags);
Inputs	a0	struct BoardInfo *bi
	a1	APTR featuredata
	d0	ULONG type
	a2	struct TagItem *tags

This function shall return attributes of board-specific features. The featuredata pointer is a pointer to a feature specific structure whose type is given by the type argument. Such structures are created through CreateFeature() and are opaque to the caller. The tags carry additional data. At the time of writing, the following features are supported by the rtg.library:

Type	Feature
SFT_FLICKERFIXER	Controls an on-board flicker fixer
SFT_MEMORYWINDOW	Controls a memory-overlay
SFT_VIDEOWINDOW	Controls an overlay region for externally provided video sources
SFT_VIDEOCAPTURE	Controls recording of video into a memory buffer

The function returns a feature-specific result code in d0.

The tags for this function are defined in the <boardinfo.h> file. The following tags are currently defined. "Set" indicates that the P96 core communicates the feature into the driver, "Get" indicates that the P96 core expects that the driver supplies the feature.

Tag	Type	Get/Set	Meaning
FA_Onboard	bool	Set	Indicates if the bitmap (if any) associated to the feature is in the video RAM.
FA_Active	bool	Set	Indicates whether the hardware implementing the feature is enabled/disabled.
FA_Left	LONG	Set	Left edge of the feature region relative to the left edge of the onboard bitmap.
FA_Top	LONG	Set	Top edge of the feature region relative to the top edge of the onboard bitmap.
FA_Width	LONG	Set	Width of the feature region in screen pixels
FA_Height	LONG	Set	Height of the feature region in screen pixels
FA_Format	RGBFTYPE	Get & Set	RGB type of the data represented by the feature
FA_Occlusion	bool	Set	Indication if parts of the region is occluded by a layer
FA_SourceWidth	LONG	Get & Set	Horizontal pixel count mapped into the feature region, scaling applies if different from region width
FA_SourceHeight	LONG	Get & Set	Vertical pixel count mapped into the feature region, scaling applies if different from region height
FA_MinWidth	LONG	Get	Minimum width a feature region can be scaled to.
FA_MinHeight	LONG	Get	Minimum height a feature region can be scaled to.
FA_MaxWidth	LONG	Get	Maximum width a feature region can be scaled to.
FA_MaxHeight	LONG	Get	Maximum height a feature region can be scaled to.
FA_Interlace	bool	Set	Indication that the source mapped by the feature is interlaced.
FA_PAL	bool	Set	Indication that the source mapped by the feature is a 50Hz PAL signal (as opposed to 60Hz NTSC)
FA_BitMap	struct BitMap *	Get	Pointer to a bitmap that represents the source pixels of the feature
FA_Brightness	LONG	Get & Set	Feature specific brightness scale factor between 0 and MAX_ULONG
FA_ModeInfo	struct ModeInfo *	Set	Pointer to the ModeInfo structure describing the mode on which the feature is mapped
FA_ModeFormat	RGBFTYPE	Set	RGB type of the screen the feature region is to be mapped on
FA_Colors	struct ColorSpec *	Set	Pointer to an intuition-type ColorSpec structure defining a potential palette
FA_Colors32	LONG *	Set	Pointer to an intution type 32-bit ranged palette specification
FA_NoMemory	bool	Set	Indicator if no video RAM shall be allocated for the feature
FA_RenderFunc	void __asm (*)(...)	Set	ABMA_RenderFunc compatible function that moves a bitmap on board
FA_SaveFunc	void __asm (*)(...)	Set	ABMA_SaveFunc compatible function that migrates an on-board bitmap
FA_UserData	APTR	Set	Deposits opaque user data into the feature bitmap, retrievable by ABMA_UserData
FA_Alignment	LONG	Set	Logical alignment of feature bitmap, or ~0 for alignment to MMU pages
FA_ConstantBytesPerRow	bool	Set	If set, aligns the bitmap width to at least the mode width in bytes
FA_DoubleBuffer	bool	Set	Indication whether the feature is double-buffered
FA_Pen	LONG	Set	RGB mode specific pen to identify opaque regions (e.g. blue-screen)
FA_ModeMemorySize	ULONG	Set	VGA memory in bytes required by active mode (allows early-out on low mem)
FA_ClipLeft	LONG	Get & Set	Number of source pixels on the left edge to remove from the feature region
FA_ClipTop	LONG	Get & Set	Number of source pixels on the top edge to remove from the feature region
FA_ClipWidth	ULONG	Get & Set	Source width of the feature to clip to
FA_ClipHeight	ULONG	Get & Set	Source height of the feature to clip to
FA_BitmapWidth	LONG	Set	Width of the screen bitmap in pixels the feature region appears on.
FA_BitmapHeight	LONG	Set	Height of the screen bitmap in pixels the feature region appears on.

SetFeatureAttrs

Synopsis	SetFeatureAttrs(bi, featuredata, type, tags);
Inputs	a0	struct BoardInfo *bi
	a1	APTR featuredata
	d0	ULONG type
	a2	struct TagItem *tags

This function shall modify board-specific features where the type of the feature is given in d0, a pointer to a feature specific structure in a1 and a tag-list identifying the requested modifications in a2. The arguments are otherwise identical to that of GetFeatureAttrs(). The function returns a feature-specific result code in d0.

CreateFeature

Synopsis	CreateFeature(bi, type, tags);
Inputs	a0	struct BoardInfo *bi
	d0	ULONG type
	a1	struct TagItem *tags

This function shall create an opaque structure that controls board-specific features such as a flicker fixer or a video overlay. The function returns a pointer to this structure, which can be later modified by SetFeatureAttrs() or whose elements can be read by GetFeatureAttrs(). For the list of supported features, see GetFeatureAttrs().

DeleteFeature

Synopsis	DeleteFeature(bi, feature, type);
Inputs	a0	struct BoardInfo *bi
	a1	APTR feature
	d0	ULONG type

This function shall delete a board-specific feature formerly created by CreateFeature(). The pointer to an opaque feature-specific pointer is passed in in a1, the type of the feature in d0. This function returns a success code. For the list of currently supported features, see GetFeatureAttrs().

Dynamic data

The remaining members of the BoardInfo structure are for exclusive use by the rtg.library and shall not be modified by any function; they shall not be interpreted in any particular way.

Development Setup

Environment

In order to setup a programming environment for development of P96 chip or card drivers, the following steps should be followed:

create a Picasso96Develop directory,
add an assign "p96:" to it,
extract the CardDevelop.lha and Develop.lha archives to this directory,
get current versions of PhxAss and PhxLnk from Aminet and install them,
copy the sc/env/smake.def file to SC:ENV to get our default translation settings, otherwise you will have to add the missing stuff to the makefile,
change the SMakeFile in p96:HardWare to use "P96:Include" instead of "P96:PublicInclude" and change the line "all: $(CARDS) $(CHIPS)" to "all: <names of the targets you have got sources for...>",
try to make the targets for the supplied source files.

This setup assumes that you have the SAS C compiler installed. The example makefiles make use of the capabilites of SMake, adjustments may be required for other make utilities.

Languages

I would prefer to use C for programming my code. Is there any problem?

Some drivers are, in fact, written in C, so it is certainly doable. Since the BoardInfo function API passes arguments in registers, the compiler should either support register parameters, or assembly stub functions are needed to adjust the calling convention. Also note that some functions of the BoardInfo API are expected to preserve all registers. Since most compilers use d0-d1/a0-a1 as scratch registers, a small assembler stub function is required to preserve these registers.

As a matter of precaution, do not use static or global variables as your driver may be used by multiple cards or multiple chips at once, i.e. the same code may be shared by multiple boards. If you need to store side information that has to be preserved across calls, chip drivers may use the BoardInfo->ChipData and card drivers may use the BoardInfo->CardData members. These members are not touched by the rtg.library itself.

P96 Driver Development

Contents

Introduction

struct BoardInfo

FindCard

InitCard

InitChip

P96 hierarchy overview

Writing a new Driver

Overview

Basic Functionality

Constant data

Functions

Hardware Sprite Support

Blitter Support

Screen Dragging Support

Extra Stuff

Special Features

Memory Management

Driver private data

In Detail

Constant data

RegisterBase

MemoryBase

MemoryIOBase

MemorySize

MaxPlanarMemory

MemorySpaceBase

MemorySpaceSize

MaxBMWidth

MaxBMHeight

BoardName

BoardType

BitsPerCannon

Flags

BIB_HARDWARESPRITE

BIB_NOMEMORYMODEMIX

BIB_NEEDSALIGNMENT

BIB_CACHEMODECHANGE

BIB_VBLANKINTERRUPT

BIB_HASSPRITEBUFFER

BIB_DBLSCANDBLSPRITEY

BIB_ILACEHALFSPRITEY

BIB_DBLCLOCKHALFSPRITEX

BIB_ILACEDBLROWOFFSET

BIB_INTERNALMODESONLY

BIB_FLICKERFIXER

BIB_VIDEOCAPTURE

BIB_VIDEOWINDOW

BIB_BLITTER

BIB_VGASCREENSPLIT

BIB_PALETTESWITCH

BIB_DACSWITCH

BIB_HIRESSPRITE

BIB_BIGSPRITE

BIB_BORDEROVERRIDE

BIB_BORDERBLANK

BIB_INDISPLAYCHAIN

BIB_QUIET

BIB_NOMASKBLITS

BIB_NOP2CBLITS

BIB_NOBLITTER

BIB_SYSTEM2SCREENBLITS

BIB_GRANTDIRECTACCESS

BIB_OVERCLOCK

SoftSpriteFlags

RGBFormats

MaxHorValue and MaxVerValue

MaxHorResolution and MaxVerResolution

PixelClockCount

Functions

AllocCardMem

FreeCardMem

AllocCardMemAbs

ReInitMemory

SetSwitch

SetColorArray

SetDAC

SetGC

SetPanning