Writing a Picasso96 Hardware Driver

This is version 1.0 of this document. To check for updates of this document, contact jens@icomp.de.

Contents

1. Introduction
2. Hierarchy
3. Writing a new Driver
3.1 Overview
3.2 In Detail
4. Development Setup
4.1 Environment
4.2 Languages

Introduction

This document specifies the P96 interface between the rtg.library and the card and chip drivers.

Graphics boards for the Amiga consist typically of two components: the Amiga expansion card with the glue logic and the optional video switch and a standard PC-VGA chip. The former interface is provided by the card driver, the latter by the chip driver.

The rationale for this functional division is to ease support of similar graphics cards that share the same VGA chip, even though the glue logic on the board is different. The corresponding chip driver can be shared between boards.

For example, the PicassoII(+), the GVP Spectrum and the Piccolo share the same chip driver but use different card drivers. Hence both cards profit from an update of their single common chip driver.

Even though it is advisable to separate drivers in a chip and card driver, monolithic drivers are possible; in such a case, all functionalities will be provided by the card driver alone.

P96 card drivers are standard Amiga libraries that shall provide two additional function entries at offsets -0x1e and -0x24:

P96 chip drivers shall provide only one additional function at offset -0x1e:

struct BoardInfo

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->ChipFlags may be updated according to the capabilities of the card.

bi->HardInterrupt may be initialized and registered through AddIntServer(). A typical interrupt would be a vertical retrace interrupt. On which interrupt level interrupts are triggered is board specific.

The bi->SetInterrupt function may be initialized to enable or disable board specific interrupts.

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->PaletteChipType to the type of the RAMDAC chip, if a separate RAMDAC is required. If not so, this member shall be initialized to the same value as the GraphicsControllerType.

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.

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

Picasso96 hierarchy overview

Writing a new Driver

As a guideline, the following steps should be followed when starting a new driver from scratch:
  1. get the driver to work as a dumb frame buffer,
  2. get the optional hardware sprite working,
  3. get the blitter working,
  4. 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:

Functions:

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

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.

Screen Dragging Support
What is needed to support screen dragging?

Extra Stuff

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.

Memory Management
I have to override the Picasso96 memory management functions because my memory has to be treated specially

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:

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.

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.

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, the CPU caching mode of the board memory is set to non-serialised (040) or imprecise (060). If this bit is set, then MemorySpaceBase and MemorySpaceSize shall be initialized.
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.

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_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.

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.

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 a 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
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
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
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.

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

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

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 d4.

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, XOffset, YOffset, RGBFormat);
Inputs:a0:struct BoardInfo *bi
a1:UBYTE *Memory
d0:UWORD Width
d1:WORD XOffset
d2:WORD YOffset
d7:RGBFTYPE RGBFormat

This function shall set the view origin of a display which might be overscanned. 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.

CalculateBytesPerRow:
Synopsis:CalculateBytesPerRow(bi, Width, RGBFormat);
Inputs:a0:struct BoardInfo *bi
d0:UWORD Width
d7:RGBFTYPE RGBFormat
Result:d0:UWORD Count

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.

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

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

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

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

This function transforms 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
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. Note that the return value is a bitmask, though the RGBFormat passed in is a bit number.

When switching the RGBFormat, the rtg.library will migrate all those bitmaps that are not compatible with the new format. As this function is used to trigger the bitmap migration, its return value shall be consistent with aperture window reconfigurations triggered by SetMemoryMode().

Typically, the planar format cannot coexist with any other format as the legacy VGA logic addresses the memory then as four independent planes.

Boards offering aperture windows for transparent byte or word swaps may also have to migrate bitmaps if the aperture mode is changed.

SetDisplay:
Synopsis:SetDisplay(bi, state);
Inputs:a0:struct BoardInfo *bi
d0: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 and Denominator members of the ModeInfo structure passed in.

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

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.

SetMemoryMode:
Synopsis:SetMemoryMode(bi, RGBFormat);
Inputs:a0:struct BoardInfo *bi
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 should 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
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
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
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.

WaitVerticalSync:
Synopsis:WaitVerticalSync(bi);
Inputs:a0:struct BoardInfo *bi

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

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.

SetInterrupt:
Synopsis:SetInterrupt(bi, state);
Inputs:a0:struct BoardInfo *bi
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 waits 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 disabled or enables 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
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 that defines which (logical) planes are affected by the copy for planar or chunky bitmaps. It can be ignored for direct color modes.

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>. Line->X and Line->Y is the origin of the line in the video RAM region. Line->Length the length of the line in pixels, Line->dX and Line->dY the coordinate differences in horizontal and vertical direction. They are positive if the line extends to the right or bottom, and negative if the line extends to the top or left.

Line->sDelta is the minimum of the absolute values of Line->dX and Line->dY, Line->lDelta the maximum of the two. Line->twoSDminusLD is 2*Line->sDelta - Line->lDelta. Line->Horizontal is true if the line width is larger or equal than the line height, it is false otherwise. Line->Xorigin and Line->Yorigin are the left-top edge of the line. These values are computed by the rtg.library as a service for this function, but may or may not be used by this function.

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.

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

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 the Amiga Blitter MinTerms encoding of the graphics.library.

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.

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.

Mask is a bitmask that identifies which bitplanes shall be considered for the conversion.

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
d0.w: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 topmost screen is started at the memory computed by SetPanning(), and the bottommost screen starts at address 0. In particular, it ensures that the bottommost screen does not pan and uses the same RGBFormat than the topmost 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.

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

  • 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.

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:
  1. create a Picasso96Develop directory,
  2. add an assign "p96:" to it,
  3. extract the CardDevelop.lha and Develop.lha archives to this directory,
  4. get current versions of PhxAss and PhxLnk from Aminet and install them,
  5. 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,
  6. 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...>",
  7. 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.

thor, August 2020