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
	< sc:include/graphics/modeid.h> < sc:include/graphics/displayinfo.h>