Fills in the entries of a BITMAPINFO structure with values that will give maximum performance for memory-to-screen 1:1 identity blts using WinG.
BOOL WinGRecommendDIBFormat(BITMAPINFO far *pHeader)
Parameters
| pHeader | Points to a BITMAPINFO structure to receive the recommended DIB format. |
Return Value
Returns non-zero if successful. Otherwise, returns zero.
Comments
pHeader must point to enough memory to hold a BITMAPINFOHEADER and 3 DWORDs for BI_BITFIELDS. WinGRecommendDIBFormat will not return a color table.
For any combination of hardware and software, there will be one DIB format that WinG can copy fastest from memory to the screen. WinGRecommendDIBFormat returns the optimal format for blting DIBs with no stretching and no complex clipping using an identity palette. If your application makes heavy use of another blt type (such as 1:2 stretching or complex clipping regions), you may want to perform top-down and bottom-up timing comparisons yourself at run-time to determine the most efficient method for your needs.
In many cases, WinG will find that it can copy a DIB to the screen faster if the DIB is in top-down format rather than the usual bottom-up format. WinGRecommendDIBFormat will set the biHeight entry of the BITMAPINFOHEADER structure to -1 if this is the case, otherwise biHeight will be set to 1. See the DIB Orientation article for more information about these special DIBs.
Code that uses WinGRecommendDIBFormat should never assume that it will recommend an 8-bit format, as this may change depending on the run-time platform.
Example
See the WinGCreateBitmap API for sample code that uses WinGRecommendDIBFormat.
See Also