DTWAIN_SetPDFPageSize

The following function is available only with DTWAIN / PDF.

The DTWAIN_SetPDFPageSize sets the current page size of the PDF page.

DTWAIN_BOOL DTWAIN_SetPDFPageSize (

Parameters

Source

An open TWAIN Source.

PageSize

The current page size,

CustomWidth

Custom width in points.

CustomHeight

Custom height in points.

Return Values

The return value is TRUE if successful.  Otherwise FALSE is returned.

Comments

The DTWAIN_SetPDFPageSize sets the current page size of the PDF page when acquiring images to PDF file(s) using DTWAIN_AcquireFile or DTWAIN_AcquireFileEx.

The PageSize argument can be one of the DTWAIN Paper Size constants, DTWAIN_PDF_CUSTOMSIZE, DTWAIN_PDF_PIXELSPERMETERSIZE, or DTWAIN_PDF_VARIABLEPAGESIZE. If one of the DTWAIN Frame Size constants are used or DTWAIN_PDF_VARIABLEPAGE is specified, the CustomWidth and CustomHeight arguments are ignored.

If DTWAIN_PDF_CUSTOMSIZE is used, the page width and height are determined by the CustomWidth and CustomHeight arguments.  Note that these arguments must be specified in terms of points.  There are 72 points per inch, therefore a custom page size of 10" x 12" would be specified as 720 x 864 points.

If DTWAIN_PDF_PIXELSPERMETERSIZE is used, the page width and height are proportional to the size of the image in pixels per unit.  For all images produced by a TWAIN device, the unit of measurement within the bitmap is based on pixels per meter (39.37 inches per meter).  So for  example, if an image has dimensions 2486 X 3488, and the pixel per meter setting for the image is 11,814 for both width and height, the resulting PDF page size would be computed thusly:

11814 / 39.37 is approximately 300 pixels per inch.

2486 / 300 = 8.28 inches (horizontal size)

3488 / 300 = 11.62 inches (vertical size)

So the resulting PDF page will be 8.28 X 11.62 inches, or approximately A4 paper size.  The pixel-per-meter setting, as well as the bitmap width and height, are all part of the bitmap information returned by the TWAIN driver before and after acquiring the image.  If this information returned by the TWAIN driver is wrong or missing, the PDF page will be distorted.  Therefore DTWAIN assumes that the TWAIN driver describes the image that has been acquired correctly.

If DTWAIN_PDF_VARIABLEPAGESIZE is specified, the PDF page is sized to the actual size of the image.  The size of the page is determined by the pixel width and height of the image.  A one-to-one mapping of the points to pixels is done.  For example, if no scaling is done, an image of 800 x 600 pixels is fitted to a PDF page of 800 x 600 points.  This allows the acquired image to fit perfectly without distortion, since the page is fitted to the image instead of the image being fitted to the page.  If DTWAIN_PDF_VARIABLEPAGE is used, and there is also custom scaling (DTWAIN_SetPDFPageScale using DTWAIN_PDF_CUSTOMSCALE), the image is scaled and a PDF page is created with the same dimensions as the scaled image.

The DTWAIN_PDF_PIXELSPERMETERSIZE is the best setting to use if what is desired is the closest match of the PDF page size to the actual size the image represents.  All other settings will usually scale the page size, unless the scaled page matches what DTWAIN_PDF_PIXELSPERMETERSIZE would have produced.

By default, the page size is set for DTWAIN_FS_USLETTER (8.5" x 11" or in points,  612 x 792).

Example

To set the page size to A4:

DTWAIN_SetPDFPageSize( Source, DTWAIN_FS_A4, 0.0, 0.0 );

To set the page size to LEGAL

DTWAIN_SetPDFPageSize( Source, DTWAIN_FS_USLEGAL, 0.0, 0.0 );

To set the page size to 5" x 7.5"

DTWAIN_SetPDFPageSize( Source, DTWAIN_PDF_CUSTOMSIZE, 5.0*72.0, 7.5*72.0 );

The last two arguments multiply 5 by 72 and 7.5 by 72, since there are 72 points per inch.

To set the page size equal to the image size:

DTWAIN_SetPDFPageSize( Source, DTWAIN_FS_VARIABLEPAGE, 0.0, 0.0 );

To set the page size equal to the image size and scale the image by half in both x and y directions:

DTWAIN_SetPDFPageSize( Source, DTWAIN_PDF_VARIABLEPAGE, 0.0, 0.0 );

DTWAIN_SetPDFPageScale( Source, DTWAIN_PDF_CUSTOMSCALE, 50.0, 50.0 );

To set the page size equal to the pixel per meter setting of the image:

DTWAIN_SetPDFPageSize( Source, DTWAIN_PDF_PIXELSPERUNITSIZE, 0.0, 0.0 );

TWAIN State Transitions

The Source must be in State 4. or higher

Prerequisite Function Call(s)

DTWAIN_SysInitialize

DTWAIN Source Selection Function

For languages that have difficulties with DTWAIN_FLOAT parameters, the alternate function that can be used as a replacement for DTWAIN_SetPDFPageSize is DTWAIN_SetPDFPageSizeString.

See Also

PDF File Options