DirectDraw Functionality Test (Compact 2013)

Article
03/28/2014

3/26/2014

The DirectDraw depth test for Windows Embedded Compact 2013 provides comprehensive coverage of the IDirectDraw and IDirectDrawSurface methods. This test runs only if the display hardware on the target device supports DirectDraw. It is organized into different groups.

Functionality	IDirectDraw methods
Cooperative levels	IDirectDraw::SetCooperativeLevel, IDirectDraw::TestCooperativeLevel
Creating objects	IDirectDraw::CreateClipper, IDirectDraw::CreateSurface
Device capabilities	IDirectDraw::GetCaps, IDirectDraw::GetDeviceIdentifier
Display modes	IDirectDraw::EnumDisplayModes, IDirectDraw::GetDisplayMode, IDirectDraw::GetMonitorFrequency, IDirectDraw::RestoreDisplayMode, IDirectDraw::SetDisplayMode, IDirectDraw::WaitForVerticalBlank
Display status	IDirectDraw::GetScanLine, IDirectDraw::GetVerticalBlankStatus
Miscellaneous	IDirectDraw::GetAvailableVidMem, IDirectDraw::GetFourCCCodes
Surface management	IDirectDraw::EnumSurfaces, IDirectDraw::FlipToGDISurface, IDirectDraw::GetGDISurface, IDirectDraw::GetSurfaceFromDC, IDirectDraw::RestoreAllSurfaces

Functionality	IDirectDrawSurface methods
Allocating memory	IDirectDrawSurface::IsLost, IDirectDrawSurface::Restore
Attaching surfaces	IDirectDrawSurface::EnumAttachedSurfaces
Blitting	IDirectDrawSurface::AlphaBlt, IDirectDrawSurface::Blt, IDirectDrawSurface::GetBltStatus
Color keying	IDirectDrawSurface::GetColorKey, IDirectDrawSurface::SetColorKey
Device capabilities	IDirectDrawSurface::GetCaps
Device contexts	IDirectDrawSurface::GetDC, IDirectDrawSurface::ReleaseDC
Flipping	IDirectDrawSurface::Flip, IDirectDrawSurface::GetFlipStatus
Locking surfaces	IDirectDrawSurface::Lock, IDirectDrawSurface::Unlock
Miscellaneous	IDirectDrawSurface::GetDDInterface
Overlays	IDirectDrawSurface::EnumOverlayZOrders, IDirectDrawSurface::GetOverlayPosition, IDirectDrawSurface::SetOverlayPosition, IDirectDrawSurface::UpdateOverlay, IDirectDrawSurface::UpdateOverlayZOrder
Surface clipper	IDirectDrawSurface::GetClipper, IDirectDrawSurface::SetClipper
Surface characteristics	IDirectDrawSurface::GetPixelFormat, IDirectDrawSurface::GetSurfaceDesc
Surface palettes	IDirectDrawSurface::GetPalette, IDirectDrawSurface::SetPalette

Test Prerequisites

Your device must meet the following requirements before you run this test.

The following table shows the hardware requirement for the DirectDraw Test.

Requirement	Description
Video subsystem	A video subsystem that supports DirectDraw

The following table shows the software requirements for the DirectDraw Functionality Test.

Requirements	Description
Tux.exe	Tux test harness, required for executing the test
Kato.dll	Kato logging engine, required for logging test data
DDfunc.dll	Test library
ddi.dll.cfg	Configuration file for supported driver capabilities

Before you run the DirectDraw Functionality Test, you must include DirectX and DirectDraw in your OS design. The SYSGEN_DDRAW Sysgen variable adds the required functionality to your OS design.

The test needs the configuration files, to mention the pixel formats supported by their display drivers. Before running the test, make sure that a config file is present which has all the supported capabilities. Else, the tests will run through the standard surface formats expecting them to be supported and may fail [if they do not support them].

We have different .cfg files for different display drivers.

ddi_rflat.dll.cfg

ddi_ragexl.dll.cfg

ddi_perm3.dll.cfg

ddi_mq200.dll.cfg

ddi_flat.dll.cfg

ddi_ati.dll.cfg

ddi.dll.cfg

ddi_ncg.dll.cfg

pxa27x_ms_v2_lcd.dll.cfg

ddi_iMX27.dll.cfg

ddraw_ipu.dll.cfg

zylonite_lcd.dll.cfg

ddi_tievm3530.dll.cfg

s3c6410_disp.dll.cfg

All these files have details about the pixel formats that the display driver does and does not support. Below are the example formats in which the data is represented. The BSP supports 4 bits each of Alpha, Red, Green, Blue with a pre-multiplied [pm] factor.

All the RGB values are already pre-multiplied with the Alpha value, so it can be directly blended. But in ARGB cases, this operation should be done during alpha-blending. For this, we do pre-multiplying. For example:

pfARGB4444pm=1

pfRGB0888=1

To create a configuration file

The name of the configuration file follows the format of the file extension ".cfg" appended to the name of the driver DLL. For example, if the name of the display driver DLL is "ddi_ragexl.dll", the test will search for the file "ddi_ragexl.dll.cfg" in the release directory.

This configuration file contains the details of the pixel format that the display driver does and does not support.

The following is a list of the pixel formats that can be part of the configuration file:

pfPal8

pfRGB555

pfRGB565

pfBGR565

pfARGB155

pfARGB4444

pfARGB1555pm

pfARGB4444pm

pfRGB888

pfBGR888

pfRGB0888

pfBGR0888

pfARGB8888

pfABGR8888

pfARGB8888pm

pfABGR8888pm

pfYUVYUYV

pfYUVUYVY

pfYUVYV12

pfYUVNV12

pfYUVI420

pfYUVYUY2

Significance of the values assigned to parameters in the configuration file

The parameters mentioned in the configuration file may be set to any of the following values:

Value	Description
1	Indicates that the driver supports the pixel format. If the driver supports the pixel format, the test will pass; else it will fail.
-1	Indicates that the driver does not support the pixel format. If the driver does not support the pixel format, the test will pass; else it will fail.
0 or no value specified	Indicates the default value. The default list in the test is searched to check if it is a supported/unsupported pixel format. This default list in the test is very generic. The test will fail if a supported format in the default list is actually not supported by the display driver, and an unsupported format in the default list is supported by the driver.

Note: When you run the DirectDraw Functionality Test, the Windows Embedded Compact Test Kit (CTK) temporarily copies files to the root directory of the target device. While the test runs, the test dynamically consumes program memory on the device. Before running the test, verify that there is at least 0.9 MB of free storage memory on the device. Also verify that there is at least 1.5 MB of free program memory on the device. If there is not sufficient space in the root directory of the device or there is not sufficient program memory, the test cannot run.

Subtests

The table below lists the subtests included in this test.

SubTest ID	Description
100	DirectDrawCreate: Verifies that an instance of a DirectDraw object of the active display driver is created.
102	DirectDrawCreateClipper: Verifies that an instance of a DirectDrawClipper object is created.
104	DirectDrawEnumerateEx: Enumerates all DirectDraw devices installed on the system.
200	IDirectDraw::CreateClipper: Verifies that a DirectDrawClipper object is created.
202	IDirectDraw::GetCaps: Retrieves the capabilities of the hardware abstraction layer (HAL) twice. Test verifies that capabilities are retrieved successfully and the HAL capabilities from different calls are consistent.
204	IDirectDraw::SetCooperativeLevel: Verifies that the SetCooperativeLevel function succeeds when a variety of flags are set.
206	IDirectDraw::ReceiveWMUnderFSE: Creates a primary surface and a dummy window. Verifies that consistent WM_ACTIVATE messages are sent when the window is activated.
304	IDirectDraw::CreateSurface(Normal Cooperative Level): Cycles through the different surface types (disregard what has been reported as being supported) and verifies if the surface can be created successfully. The test case fails if a supported surface cannot be created or if an unsupported surface can be created.
308	IDirectDraw::EnumDisplayModes(Normal Cooperative Level): Enumerates the DirectDraw display modes, verifies that the enumeration completes. Displays the number of display modes enumerated.
314	IDirectDraw::GetFourCCCodes(Normal Cooperative Level): Verifies the behavior when the number of entries passed to the function GetFourCCCodes is more than or less than the number of FOURCC codes supported. Known issues: If the number of entries passed to method GetFourCCCodes is too small to accommodate all the codes, GetFourCCCodes doesn’t update the number of entries.
404	IDirectDraw::CreateSurface(Exclusive Cooperative Level): Cycles through the different surface types (disregard what has been reported as being supported) and verifies if the surface can be created successfully. The test case fails if a supported surface cannot be created or if an unsupported surface can be created.
408	IDirectDraw::EnumDisplayModes(Exclusive Cooperative Level): Enumerates the DirectDraw display modes, verifies that the enumeration completes. Displays the number of display modes enumerated.
410	IDirectDraw::FlipToGDISurface: Verifies consistent behavior when flipping to and away from GDI surface.
412	IDirectDraw::SetDisplayMode and IDirectDraw::GetDisplayMode: Verifies SetDisplayMode and GetDisplayMode functions set and return consistent display modes.
414	IDirectDraw::GetFourCCCodes(Exclusive Cooperative Level): Verifies the behavior when the number of entries passed to the function GetFourCCCodes is more than or less than the number of FOURCC codes supported. Known issues: If the number of entries passed to the method GetFourCCCodes is too small to accommodate all the codes, GetFourCCCodes doesn’t update the number of entries.
426	IDirectDraw::RestoreDisplayMode: Verifies that a call to the RestoreDisplayMode function resets the mode of the display device hardware.
502	IDirectDrawSurface::AddOverlayDirtyRect(Normal Cooperative Level): Function AddOverlayDirtyRect is not implemented. Verifies that the AddOverlayDirtyRect function appropriately handles inputs.
503	IDirectDrawSurface::AlphaBlt(NORMAL Cooperative Level): Executes a variety of blits to assorted surfaces. This test case fails if any blits are unsuccessful.
504	IDirectDrawSurface::Blt(NORMAL Cooperative Level): Executes a variety of blits to and from assorted surfaces. This test case fails if any blits are unsuccessful.
510	IDirectDrawSurface::EnumAttachedSurfaces(NORMAL Cooperative Level): Enumerates the surfaces attached to the given primary surface.
514	IDirectDrawSurface::Flip: Executes a variety of blits to a flipping chain and verifies that the flips are successful and that all surfaces display correctly. This test case fails if any flips or surface verifications fail.
518	IDirectDrawSurface::GetBltStatus(NORMAL Cooperative Level): Verifies that the GetBltStatusfunction function appropriately handles a variety of valid and invalid input conditions.
520	IDirectDrawSurface::GetCaps(NORMAL Cooperative Level): Retrieves the capabilities of various surfaces, and verifies that the operation is successful.
522	IDirectDrawSurface::GetClipper/IDirectDrawSurface::SetClipper(NORMAL Cooperative Level): Verifies that the SetClipper function attaches a clipper object to or deletes one from a surface. Verifies that GetClipper function retrieves the DirectDrawClipper object associated with the surface.
524	IDirectDrawSurface::GetColorKey/IDirectDrawSurface::SetColorKey(NORMAL Cooperative Level): Verifies that the GetColorKey and SetColorKey functions set and retrieve consistent color key values for the DirectDrawSurface object.
526	IDirectDrawSurface::GetDC(NORMAL Cooperative Level): Verifies that the GetDC function appropriately handles a variety of testing of source surfaces.
528	IDirectDrawSurface::GetFlipStatus(NORMAL Cooperative Level): If the source surface is part of a surface flipping structure, verifies that the GetFlipStatus function returns consistent information.
534	IDirectDrawSurface::GetPixelFormat(NORMAL Cooperative Level): Verifies that the GetPixelFormat function returns consistent information about the color and pixel format of the surface.
536	IDirectDrawSurface::GetSurfaceDesc(NORMAL Cooperative Level): Verifies that the function GetSurfaceDesc returns consistent information about the description of the surface.
540	IDirectDrawSurface::IsLost/IDirectDrawSurface::Restore(NORMAL Cooperative Level): Executes various ways that a surface can be lost. Verifies that the surface is lost as expected. Verifies the behavior of the Restore function.
542	IDirectDrawSurface::Lock/IDirectDrawSurface::Unlock(NORMAL Cooperative Level): Verifies that the calls to the Lock and Unlock functions succeed.
543	Verifies that the Unlock function behaves consistently after moving/resizing and destroying the window.
544	IDirectDrawSurface::ReleaseDC(NORMAL Cooperative Level): Verifies that calls to ReleaseDC function succeed.
556	Tests the behavior of primary surfaces in the windowed mode by setting different windows.
602	IDirectDrawSurface::AddOverlayDirtyRect(EXCLUSIVE Cooperative Level): Function AddOverlayDirtyRect is not implemented. Verifies that the AddOverlayDirtyRect function appropriately handles inputs.
603	IDirectDrawSurface::AlphaBlt(EXCLUSIVE Cooperative Level): Executes a variety of blits to assorted surfaces. This test case fails if any blits are unsuccessful.
604	IDirectDrawSurface::Blt(EXCLUSIVE Cooperative Level): Executes a variety of blits to and from assorted surfaces. This test case fails if any blits are unsuccessful.
610	IDirectDrawSurface::EnumAttachedSurfaces(EXCLUSIVE Cooperative Level): Enumerates the surfaces attached to the given primary surface.
614	Executes a variety of blits to a flipping chain and verifies that the flips are successful and that all surfaces display correctly. This test case fails if any flips or surface verifications fail.
618	IDirectDrawSurface::GetBltStatus(EXCLUSIVE Cooperative Level): Verifies that the GetBltStatus function appropriately handles a variety of valid and invalid input conditions.
620	IDirectDrawSurface::GetCaps(EXCLUSIVE Cooperative Level): Retrieves the capabilities of various surfaces, and verifies that the operation is successful.
622	IDirectDrawSurface::GetClipper/IDirectDrawSurface::SetClipper(EXCLUSIVE Cooperative Level): Verifies that the SetClipper function attaches a clipper object to or deletes one from a surface. Verifies that the GetClipper function retrieves the DirectDrawClipper object that is associated with the surface.
624	IDirectDrawSurface::GetColorKey/IDirectDrawSurface::SetColorKey(EXCLUSIVE Cooperative Level): Verifies that the GetColorKey and SetColorKey functions set and retrieve consistent color key values for the DirectDrawSurface object.
626	IDirectDrawSurface::GetDC(EXCLUSIVE Cooperative Level): Verifies that the GetDC function appropriately handles a variety of testing of source surfaces.
628	IDirectDrawSurface::GetFlipStatus(EXCLUSIVE Cooperative Level): If the source surface is part of a surface flipping structure, verifies that the GetFlipStatus function returns consistent information.
634	IDirectDrawSurface::GetPixelFormat(EXCLUSIVE Cooperative Level): Verifies that the GetPixelFormat function returns consistent information about the color and pixel format of the surface.
636	IDirectDrawSurface::GetSurfaceDesc(EXCLUSIVE Cooperative Level): Verifies that the function GetSurfaceDesc returns consistent information about the description of the surface.
640	IDirectDrawSurface::IsLost/IDirectDrawSurface::Restore(EXCLUSIVE Cooperative Level): Executes various ways a surface can be lost. Verifies that the surface is lost as expected. Verifies the behavior of the Restore function.
642	IDirectDrawSurface::Lock/IDirectDrawSurface::Unlock(EXCLUSIVE Cooperative Level): Verifies that the calls to the Lock and Unlock functions succeed.
644	IDirectDrawSurface::ReleaseDC(EXCLUSIVE Cooperative Level): Verifies that calls to the ReleaseDC function succeed.

Setting Up the Test

This test has no additional requirements, beyond the standard test environment setup.

Running the Test

The Video Capture Filter Test executes the tux -o -d ddfunc.dll command line on default execution. No other command line options are used.

Verifying the Test

When the test completes running, verify that "PASS" appears in the test log for all subtests.

Troubleshooting the Test

The following table describes some problems that you may encounter while running the DirectDraw Functionality Test and provides suggestions for resolving each problem.

Description	Resolution
Multiple test cases abort with the message "Set Display Mode Failed". The driver may be returning display modes other than the current display mode in the HALInit function and display mode switching is not supported.	Verify that the driver returns an appropriate display mode in the HALInit function.
Multiple test cases fail when trying to create surfaces in system memory. The driver may be returning an incorrect error when the CreateSurface callback function is called.	When the CreateSurface callback function is called with a surface type that the driver cannot handle, the driver should return DDHAL_DRIVER_HANDLED with ddRVal=DDERR_UNSUPPORTEDFORMAT.
Test cases fail while locking or unlocking. The driver may not be allocating video memory outside of the Graphics, Windowing, and Events Subsystem (GWES) process space.	Allocate video memory outside of the GWES process space with file mapping.

Partager via