IPrintOemUni::HalftonePattern method (prcomoem.h)

Article
04/01/2021

The IPrintOemUni::HalftonePattern method can be used with Unidrv-supported printers to create or modify a halftone pattern before it is used in a halftoning operation.

Syntax

HRESULT HalftonePattern(
  PDEVOBJ pdevobj,
  PBYTE   pHTPattern,
  DWORD   dwHTPatternX,
  DWORD   dwHTPatternY,
  DWORD   dwHTNumPatterns,
  DWORD   dwCallbackID,
  PBYTE   pResource,
  DWORD   dwResourceSize
);

Parameters

pdevobj

Caller-supplied pointer to a DEVOBJ structure.

pHTPattern

Caller-supplied pointer to a buffer that receives the method-supplied halftone pattern. Buffer size, in bytes, is:

(((dwHTPatternX * dwHTPatternY) + 3)/4) * 4 * dwHTNumPatterns

dwHTPatternX

Caller-supplied length, in pixels, of the halftone pattern, as specified by the first value in the GPD file's *HTPatternSize attribute.

dwHTPatternY

Caller-supplied height, in pixels, of the halftone pattern, as specified by the second value in the GPD file's *HTPatternSize attribute.

dwHTNumPatterns

Caller-supplied number of patterns, as specified by the GPD file's *HTNumPatterns attribute. The number of patterns can be either 1 or 3.

dwCallbackID

Caller-supplied value identifying the halftone method, as specified by the GPD file's *HTCallbackID attribute.

pResource

Caller-supplied pointer to a buffer containing a halftone pattern, as specified by the GPD file's *rcHTPatternID attribute. This can be NULL.

dwResourceSize

Caller-supplied size of the halftone pattern contained in the buffer pointed to by pResource. This is zero if pResource is NULL.

Return value

The method must return one of the following values:

Return code	Description
S_OK	The operation succeeded.
E_FAIL	The operation failed.
E_NOTIMPL	The method is not implemented.

Remarks

The IPrintOemUni::HalftonePattern method is used to create or modify a halftone pattern before Unidrv passes it to GDI. Its purpose is to allow proprietary halftone patterns to be either stored as encrypted resources or generated at run time.

If the IPrintOemUni::HalftonePattern method is implemented, and if the GPD file entry for the currently selected halftoning method includes an *HTCallbackID attribute, Unidrv calls the IPrintOemUni::HalftonePattern method before passing a halftone pattern to GDI.

If the GPD file entry for the currently selected halftoning method contains an *rcHTPatternID entry identifying an RC_HTPATTERN resource, Unidrv obtains the pattern and passes a pointer to it as the pResource parameter value. This allows you to store the pattern as an encrypted resource, and to use the IPrintOemUni::HalftonePattern method to decode the pattern. The decoded pattern should be returned in the buffer pointed to by pHTPattern.

You can also use the IPrintOemUni::HalftonePattern method to generate a halftone pattern. In this case an RC_HTPATTERN resource is not needed, so pResource is NULL. The IPrintOemUni::HalftonePattern method should generate a pattern and return it in the buffer pointed to by pHTPattern.

If the IPrintOemUni::HalftonePattern method returns one pattern, it is used for all colors. If the method returns three patterns, they must be specified in RGB order.

The following example shows an implementation of a rendering plug-in's HalftonePattern method. The method calculates the length in bytes of the HTPattern_DDK pattern array, and then copies the bytes in the pattern array to the buffer pointed to by this method's pHTPattern parameter. The pattern array can contain either one or three patterns, depending on whether the pattern is used for all colors or has separate red, green, and blue patterns. For the sake of brevity, not all elements of the pattern array are listed.

static BYTE HTPattern_DDK[256] = {
    129,  44,  59, 124, 143, 232, 166, ...
    ...
    ...
    98, 202, 130, 148, 213,  101,  163, 72
};

HRESULT __stdcall IOemUni::HalftonePattern(
    PDEVOBJ     pdevobj,
    PBYTE       pHTPattern,
    DWORD       dwHTPatternX,
    DWORD       dwHTPatternY,
    DWORD       dwHTNumPatterns,
    DWORD       dwCallbackID,
    PBYTE       pResource,
    DWORD       dwResourceSize)
{
PBYTE  pSrcPattern;
DWORD  dwLen = sizeof(HTPattern_DDK);

if (dwLen != (((dwHTPatternX * dwHTPatternY) + 3) / 4) * 4 * dwHTNumPatterns)
    return E_FAIL;

pSrcPattern = HTPattern_DDK;

while (dwLen-- > 0)
    *pHTPattern++ = *pSrcPattern++;

return S_OK;
}

An implementation of a HalftonePattern method in the rendering plug-in must be accompanied by a Halftone feature in the GPD file. The following GPD example shows a Halftone feature whose HT_PAT_DDK_16x16 option describes the customized pattern generated in the previous sample.


*Feature: Halftone

{

    *rcNameID: =HALFTONING_DISPLAY

    *HelpIndex: 12005

    *DefaultOption: HT_PATSIZE_AUTO

    *Option: HT_PATSIZE_AUTO

    {

        *rcNameID: =HT_AUTO_SELECT_DISPLAY

    }

    *Option: HT_PATSIZE_SUPERCELL_M

    {

        *rcNameID: =HT_SUPERCELL_DISPLAY

    }

    *Option: HT_PATSIZE_6x6_M

    {

        *rcNameID: =HT_DITHER6X6_DISPLAY

    }

    *Option: HT_PATSIZE_8x8_M

    {

        *rcNameID: =HT_DITHER8X8_DISPLAY

    }

    *Option: HT_PAT_DDK_16x16

    {

        *Name: "DDK 16x16"

        *HTPatternSize: PAIR(16, 16)

        *HTNumPatterns: 1

        *HTCallbackID: 1

    }

}

The IPrintOemUni::HalftonePattern method is optional. If a rendering plug-in implements this method, the plug-in's IPrintOemUni::GetImplementedMethod method must return S_OK when it receives "HalftonePattern" as input.

For more information about halftoning, see Customized Halftoning and Option Attributes for the Halftone Feature.

Requirements

Requirement	Value
Target Platform	Desktop
Header	prcomoem.h (include Prcomoem.h)