NAME
	BestModeIDA -- calculate the best ModeID with given parameters (V39)
	BestModeID  -- varargs stub for BestModeIDA()

   SYNOPSIS
	ID = BestModeIDA(TagItems)
	d0               a0

	ULONG BestModeIDA(struct TagItem *);

	ID = BestModeID(Tag1, ...)

	ULONG BestModeID(ULONG, ...);

   FUNCTION
	To determine the best ModeID to fit the parameters set in the TagList.

   INPUTS
	TagItems - A pointer to an array of TagItems.

   TAGS
	BIDTAG_DIPFMustHave (ULONG) - Mask of DIPF_ flags
	       (from DisplayInfo->PropertyFlags) that the returned ModeID
	       must have.
	       Default - NULL

	BIDTAG_DIPFMustNotHave (ULONG) - Mask of DIPF_ flags that the
	       returned ModeID must not have.
	       Default - SPECIAL_FLAGS

	BIDTAG_ViewPort (struct ViewPort *) - ViewPort for which a best-fit
	       ModeID is sought.
	       Default - NULL

	BIDTAG_NominalWidth (UWORD),
	BIDTAG_NominalHeight (UWORD) - together make the aspect ratio.
	       These values override the vp->DWidth and vp->DHeight values
	       in the given ViewPort.
	       Default - SourceID NominalDimensionInfo if BIDTAG_SourceID is
	       passed, or vp->DWidth and vp->DHeight if BIDTAG_ViewPort is
	       passed, or 640 x 200.

	BIDTAG_DesiredWidth (UWORD),
	BIDTAG_DesiredHeight (UWORD) - Used to distinguish between two
	       mode IDs with identical aspect ratios.
	       Default - same values as NominalWidth and NominalHeight.

	BIDTAG_Depth (UBYTE) - minimum the returned ModeID must support.
	       Default - vp->RasInfo->BitMap->Depth if BIDTAG_ViewPort is
	       passed, else 1.

	BIDTAG_MonitorID (ULONG) - returned ModeID must use this monitor.
	       Default - will not restrict the search to any particular monitor

	BIDTAG_SourceID (ULONG) - Use this ModeID instead of a ViewPort.
	       If specified, the DIPFMustHave mask is made up of the
	       ((DisplayInfo->PropertyFlags of this ID & SPECIAL_FLAGS) |
	        DIPFMustHave flags).
	       Default - VPModeID(vp) if BIDTAG_ViewPort was passed, else the
	       DIPFMustHave and DIPFMustNotHave masks are left unchanged.

	BIDTAG_RedBits (UBYTE),
	BIDTAG_BlueBits (UBYTE),
	BIDTAG_Greenits (UBYTE) - Minimum bits per gun the resultant
	       ModeID must support.
	       Default - 4 bits per gun.

   RESULTS
	ID      - ID of the best mode to use, or INVALID_ID if a match could
	          not be found.

   NOTES
	This function takes into account the Compatability of the Monitor
	being matched to, and the source ViewPort or ModeID.
	Incompatibilitys will cause a result of INVALID_ID.

	BIDTAG_NominalWidth, BIDTAG_NominalHeight,
	BIDTAG_DesiredWidth, BIDTAG_DesiredHeight, must all be non-0.

	The comparisons are made against the DimensionInfo->Nominal values.
	ie, this will not return a best fit against overscan dimensions.

   EXAMPLE
	IFF Display Program with a HAM image, to be displayed in the same
	monitor type as the Workbench ViewPort.

	ID = BestModeID(BIDTAG_NominalWidth, IFFImage->Width,
	                BIDTAG_NominalHeight, IFFImage->Height,
	                BIDTAG_Depth, IFFImage->Depth,
	                BIDTAG_DIPFMustHave, DIPF_IS_HAM,
	                BIDTAG_MonitorID, (GetVPModeID(WbVP) & MONITOR_ID_MASK),
	                TAG_END);

	To make an interlace version of a ViewPort:

	ID = BestModeID(BIDTAG_ViewPort, ThisViewPort,
	                BIDTAG_MustHave, DIFP_IS_LACE,
	                TAG_END);

   SEE ALSO
	<graphics/modeid.h> <graphics/displayinfo.h>