windows-server-2003/windows/core/ntgdi/gre/umpdnote.txt

+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++ Eng-callbacks for user mode printer drivers +++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++

*** All FLOATOBJ-related callbacks

    These are still available to user mode printer drivers (compile-time
    macro USERMODE_DRIVER must be defined). But drivers are strongly
    encouraged to use floating-point expressions directly.

*** Callbacks with direct user mode counterparts

    These are still available to user mode printer drivers. But drivers
    are strongly encouraged to use their user mode counterparts.

    EngGetLastError
    EngSetLastError
    EngWritePrinter
    EngGetPrinter
    EngGetPrinterDriver
    EngGetPrinterData
    EngSetPrinterData
    EngEnumForms
    EngGetForm
    EngAllocMem
    EngFreeMem
    EngAllocUserMem
    EngFreeUserMem
    EngMulDiv
    EngLoadImage
    EngFindImageProcAddress
    EngUnloadImage

*** Callbacks simulated in the user mode

    These are simulated in the client-side GDI for user mode printer drivers.
    Driver's are strongly encouraged to use Win32 APIs instead.

    EngGetPrinterDataFileName
    EngGetDriverName
    EngLoadModule
    EngFindResource
    EngFreeModule
    EngCreateSemaphore
    EngAcquireSemaphore
    EngReleaseSemaphore
    EngDeleteSemaphore
    EngQueryLocalTime
    EngMultiByteToUnicodeN
    EngUnicodeToMultiByteN
    EngMultiByteToWideChar
    EngWideCharToMultiByte
    EngGetCurrentCodePage

*** Currently supported callbacks

    BRUSHOBJ_pvAllocRbrush
    BRUSHOBJ_pvGetRbrush
    BRUSHOBJ_ulGetBrushColor
    BRUSHOBJ_hGetColorTransform


    CLIPOBJ_cEnumStart
    CLIPOBJ_bEnum
    CLIPOBJ_ppoGetPath

    FONTOBJ_cGetAllGlyphHandles
    FONTOBJ_vGetInfo
    FONTOBJ_cGetGlyphs
    FONTOBJ_pxoGetXform
    FONTOBJ_pifi
    FONTOBJ_pvTrueTypeFontFile

    PATHOBJ_vEnumStart
    PATHOBJ_bEnum
    PATHOBJ_vGetBounds
    PATHOBJ_vEnumStartClipLines
    PATHOBJ_bEnumClipLines

    STROBJ_vEnumStart
    STROBJ_bEnum
    STROBJ_dwGetCodePage

    XFORMOBJ_bApplyXform
    XFORMOBJ_iGetFloatObjXform (same as XFORMOBJ_iGetXform)

    XLATEOBJ_iXlate
    XLATEOBJ_piVector (simulated in client side)
    XLATEOBJ_cGetPalette
    XLATEOBJ_hGetColorTransform

    EngCreateBitmap
    EngCreateDeviceBitmap
    EngCreateDeviceSurface
    EngDeleteSurface
    EngLockSurface
    EngUnlockSurface
    EngEraseSurface
    EngAssociateSurface
    EngMarkBandingSurface
    EngDeletePath
    EngCreateClip
    EngDeleteClip
    EngCreatePalette
    EngDeletePalette
    EngBitBlt
    EngLineTo
    EngStretchBlt
    EngStretchBltROP
    EngAlphaBlend
    EngGradientFill
    EngTransparentBlt
    EngTextOut
    EngStrokePath
    EngFillPath
    EngStrokeAndFillPath
    EngCopyBits
    EngPlgBlt
    EngCheckAbort


*** Notable callbacks we're not going to support

    EngMapModule
    EngCreatePath
    EngPaint (obsolte)
    EngGetType1FontList (obsolete)
    EngDebugBreak (DbgBreakPoint)

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++ Special requirements on user mode printer drivers +++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

    STROBJ.pgp->gdf is NULL during DrvTextOut and STROBJ_bEnum.
    Drivers must call FONTOBJ_cGetGlyphs to get glyph bitmap
    or glyph outline. (By the way, cGlyph parameter must be 1
    for FONTOBJ_cGetGlyphs. This is true for both kernel mode
    and user mode driver.)

    During a single DDI entrypoint, drivers must balance each
    CLIPOBJ_ppoGetPath call with an EngDeletePath call. No nesting
    is allowed.

    During a single DDI entrypoint, drivers must balance each
    EngCreateClip call with EngDeleteClip call. No nesting is
    allowed.

++++++++++++++++++++++++++++++++++++++++++++++
+++++ Building user mode printer drivers +++++
++++++++++++++++++++++++++++++++++++++++++++++

    Make sure compile-time macro USERMODE_DRIVER is defined
    before including winddi.h.

    Driver graphics DLL should be built as a regular DLL
    (in the "sources" file, use TARGETTYPE=DYNLINK instead
    of TARGETTYPE=GDIDRIVER). Don't link with win32k.lib.
    Link with gdi32.lib, etc. as regular DLLs do.

    User mode printer driver graphics DLL should export a
    new entrypoint named DrvQueryDriverInfo:

        BOOL
        DrvQueryDriverInfo(
            DWORD   dwMode,
            PVOID   pBuffer,
            DWORD   cbBuf,
            PDWORD  pcbNeeded
            );

    Arguments:

        dwMode - Specify the information being queried
        pBuffer - Points to output buffer
        cbBuf - Size of output buffer in bytes
        pcbNeeded - Return the expected size of output buffer

    Return Value:

        TRUE if successful, FALSE if there is an error

    Note:
    
        Only dwMode defined at this point is DRVQUERY_USERMODE=1.
        In this case, pBuffer points to a DWORD and cbBuf=sizeof(DWORD).