OEMPREAN SAMPLE

 

Summary

This sample illustrates how you can leverage the preanalysis feature in Unidrv. This sample is built upon the redesigned version of the oemuni sample.

 

When preanalysis is enabled in the GPD, Unidrv defines the surface as a banding surface but causes the first playback to be of the entire page. Unidrv does this by setting the GDI clip window to the entire page. Unidrv allows all drawing commands to be hooked but returns before any drawing can be done. On the following passes Unidrv resets the clip window back to the original band size and bands normally. In order to enable this feature in the GPD, specify the following GPD parameter: “*PreAnalysisOptions: 8”.

 

The OEM rendering plug-in is required to hook both DrvStartBanding and DrvNextBand when this mode is enabled in the GPD. The OEM rendering plug-in must test the pptl parameter of the DrvStartBanding call to determine whether preanalysis has been enabled on this page. If the pptl parameter is NULL, then preanalysis has been enabled. The pptl parameter can be used by Unidrv since it has no meaning at this point. This parameter has not been updated with the band position and for preanalysis the band position is always be set to 0, 0. If the pptl parameter is NULL, then the OEM rendering plug-in should consider all drawing calls up to the first call to DrvNextBand to be part of preanalysis. During this phase no drawing onto the surface is allowed. You should be aware that after preanalysis, you might get more calls than you saw in the normal rendering, because primitives that cross band boundaries yield two or more DDI calls after the preanalysis pass.

 

The sample uses the bPreAnalysis flag in the OEMPDEV structure to denote whether a particular pass is the preanalysis pass or the actual rendering pass. If the bPreAnalysis flag is set, it indicates that the current pass is the preanalysis pass. The sample implements all of the drawing function hooks in ddihook.cpp. The sample uses the OEMStartBanding and OEMNextBand functions, to respectively set and reset the bPreAnalysis flag. The sample also uses the DBG_CLIPOBJ debug macro function to dump the bounds of the clipping rectangle available for preanalysis in each of the drawing functions during the preanalysis pass. To view all of the debug output in the debugger, you must set the debug level to VERBOSE. The rest of the sample is identical to the oemuni sample that illustrates a basic OEM rendering plug-in.

 

Note that the surface used during preanalysis might differ from the surface passed in during the rendering pass. Also note that during the preanalysis pass, although Unidrv calls the hooked drawing functions, it returns before any drawing is done. For this reason you should not perform any drawing on the surface during the preanalysis pass. All other preanalysis tasks should be performed during this pass. For example, certain printers need to handle black objects that intersect with color objects differently from black objects that appear by themselves. Other printers might need to halftone StretchBlt objects differently from BitBlt objects. Basically, the plug-in can analyze the objects on the page. A final point to note is that during the preanalysis pass, drawing functions should not call back into Unidrv. When the bPreAnalysis flag is set, the sample returns without calling back into Unidrv.

 

Note that this sample will not build with the Windows 2000 build environment. This version of the sample implements the IPrintOemUni2 interface which is available only on Windows XP and later. The table shown below will help identify which operating systems this sample will build/work on.

 

 

Operating System

Can sample be built in the OS?

Does sample work in the OS?

Can sample be used in a production environment for the OS?

Windows codenamed Longhorn

Yes

Yes

No

Windows Server 2003

Yes

No

No

Windows XP

Yes

No

No

Windows 2000

No

No

No

Windows Me

No

No

No

Windows 98 SE

No

No

No

 

 

Building the sample

To build the samples, run “build –cZ” from the directory. The resulting DLL will be placed in the appropriate platform directory (i.e. i386 or Alpha). To create a version with verbose debug output, add _DEBUG to the compile defines in the sources file.

 

Installing the sample

After building the sample, you can install it using the Add Printer Wizard and supplying the INF that is part of the sample when you are prompted for an INF in the wizard. The Unidrv binaries required for this driver need not be copied to the local directory containing oemdll.inf.

 

Resources

For the latest release of the Windows Device Driver Development Kit, see http://www.microsoft.com/whdc/ddk/winddk.mspx.

 

If you have questions on using or adapting this sample for your project, you can either contact Microsoft Technical Support or post your questions in the Microsoft driver development newsgroup.

 

 

File Manifest

 

Root:

 

Files                       Description

readme.htm             The documentation for this sample (this file).

oemprean.gpd          The generic GPD file for this sample.

oemprean.inf            The printer INF that will install this sample once it is built.

oemprean.ini            The printer ini file that specifies the OEM customization DLLs for this sample.

 

 

OEMPREAN directory:

 

Files                       Description

ddihook.cpp             Source module for DDI Hook routines for the rendering plug-in. (OEMBitBlt, OEMStrokePath, OEMTextOut, OEMNextBand etc.)

ddihook.h                Source module that defines the constants used to control DDI hooking. (IMPL_ALPHABLEND, IMPL_BITBLT, IMPL_NEXTBAND etc.)

debug.cpp               Source module that contains the debugging functions. (COemUniDbg::vDumpSURFOBJ, COemUniDbg::vDumpSTROBJ etc.)

debug.h                  The header file for the debug module defined in debug.cpp. (Definition of the COemUniDbg class)

devmode.cpp           Source module that contains implementation of the OEM Devmode functions. (hrOEMDevmode, bConvertOEMDevmode etc.)

devmode.h              The header for devmode.cpp.

dllentry.cpp             Source module for DLL entry functions. (DllMain)

enable.cpp              Source module that contains the enable routines for the rendering plug-in. (OEMEnableDriver, OEMEnablePDEV, OEMDisableDriver etc.)

intrface.cpp             Source module that implements the OEM COM printer customization rendering plug-in interface. (COemUni2::ImageProcessing, COemUni2::FilterGraphics etc.)

intrface.h                The header for intrface.cpp that defines the COM interface for the rendering plug-in. (Definition of the COemUni2 class)

makefile                  The generic makefile for building the code sample.

oemprean.def           The file that lists the exported functions for the sample.

oemprean.h             The header file that defines the PDEV class for the sample. (Definition and implementation of the COemPDEV class)

oemprean.rc            The resources file for the rendering plugin’s resources.

precomp.h               The header that includes the headers to precompile.

resource.h               The header file the resources file.

sources                   The generic sources file for building the code sample.