DisplayInfoHandle

From Amiga Coding
Jump to: navigation, search

A DisplayInfoHandle is internal graphics.library structure. For end user software it is considered private, but chipset display drivers supplied with AmigaOS, as well as existing RTG systems, rely on particular structure of the handle.

This information was obtained by reverse engineering DBLPal display driver and GetDisplayInfoData() function.

struct DisplayInfoHandle
{
	struct MinNode		  Node;			/*  0 Previous and next handle on this level	*/
							/*    Note that there's no struct MinList, just
							      mln_Pred of the first node is NULL and
							      mln_Succ of the last node is NULL		*/
	struct DisplayInfoHandle *Children;		/*  8 First child DisplayInfoHandle		*/
	struct DisplayInfoHandle *Parent;		/* 12 Parent DisplayInfoHandle			*/
	ULONG			  ID;			/* 16 Mode ID (or monitor ID, right-justified)  */
	struct TagItem		  Data;			/* 20 Associated data				*/
	ULONG			  Flags;		/* 28 Has something to do with GfxBase->MemType */
	ULONG			(*Get)();		/* 32 A callback routine for getting data       */
	ULONG			(*Set)();		/* 36 A callback routine for setting data       */
	struct Rectangle    	  VideoOscan;		/* 40 A copy of DimensionInfo->VideoOscan       */
	struct Rectangle	  Reserved;		/* 48 Just a guess			        */
	/* Total size of this structure is 56 bytes */
};

The display mode database in graphics.library is a 3-level tree of such structures. In the root of the tree we have one empty DisplayInfoHandle. All its fields are set to zero except Children which points to the first monitor handle. The root handle is pointed to by DisplayInfoDataBase member of GfxBase structure.

Children member of the root node points to a doubly-linked chain of monitor handles. Note that there's no standard MinList structure in the database. Just mln_Pred of the first handle is set to NULL, and mln_Succ of the last handle is set to NULL.

A monitor handle in its turn has one or more associated mode handles pointed to by its Children member.

IDs of monitor handles are most-significant halves of display mode IDs, right-justified. For example, for DBLPAL HighRes mode (ID 0x000A9000) monitor ID will be 0x0000000A.

Every handle may contain an associated information data (DisplayInfoData). These are static data bunches which are given back as they are, except DimensionInfo which is postprocessed in a special way. When a new handle is created, ti_Tag in its Data member is set to TAG_DONE. When a first data block is associated, it gets replaced with TAG_MORE, and ti_Data points to the first associated block. A detailed description of how data is stored in memory can be found in struct QueryHeader description.

Handles also may have getter and setter routines. They are not supplied by AmigaOS chipset display drivers. These functions are called after performing the actual operation (get or set) and can be used by an RTG system in order to update its internal data.