diff options
| -rw-r--r-- | public/fpdfview.h | 611 |
1 files changed, 288 insertions, 323 deletions
diff --git a/public/fpdfview.h b/public/fpdfview.h index ea45c2912c..cd96bc2a77 100644 --- a/public/fpdfview.h +++ b/public/fpdfview.h @@ -58,18 +58,17 @@ typedef unsigned char const* FPDF_LPCBYTE; // encoded), and platform dependent string typedef const char* FPDF_BYTESTRING; -typedef const unsigned short* - FPDF_WIDESTRING; // Foxit PDF SDK always use UTF-16LE encoding wide string, -// each character use 2 bytes (except surrogation), with low byte first. - -// For Windows programmers: for most case it's OK to treat FPDF_WIDESTRING as -// Windows unicode string, -// however, special care needs to be taken if you expect to process -// Unicode larger than 0xffff. -// For Linux/Unix programmers: most compiler/library environment uses 4 bytes -// for a Unicode character, -// you have to convert between FPDF_WIDESTRING and system wide string by -// yourself. +// FPDFSDK always uses UTF-16LE encoded wide strings, each character uses 2 +// bytes (except surrogation), with the low byte first. +typedef const unsigned short* FPDF_WIDESTRING; + +// For Windows programmers: In most cases it's OK to treat FPDF_WIDESTRING as a +// Windows unicode string, however, special care needs to be taken if you +// expect to process Unicode larger than 0xffff. +// +// For Linux/Unix programmers: most compiler/library environments use 4 bytes +// for a Unicode character, and you have to convert between FPDF_WIDESTRING and +// system wide string by yourself. #ifdef _WIN32_WCE typedef const unsigned short* FPDF_STRING; @@ -77,30 +76,29 @@ typedef const unsigned short* FPDF_STRING; typedef const char* FPDF_STRING; #endif -/** @brief Matrix for transformation. */ +// Matrix for transformation. typedef struct _FS_MATRIX_ { - float a; /**< @brief Coefficient a.*/ - float b; /**< @brief Coefficient b.*/ - float c; /**< @brief Coefficient c.*/ - float d; /**< @brief Coefficient d.*/ - float e; /**< @brief Coefficient e.*/ - float f; /**< @brief Coefficient f.*/ + float a; + float b; + float c; + float d; + float e; + float f; } FS_MATRIX; -/** @brief Rectangle area(float) in device or page coordination system. */ +// Rectangle area(float) in device or page coordinate system. typedef struct _FS_RECTF_ { - /**@{*/ - /** @brief The x-coordinate of the left-top corner. */ + // The x-coordinate of the left-top corner. float left; - /** @brief The y-coordinate of the left-top corner. */ + // The y-coordinate of the left-top corner. float top; - /** @brief The x-coordinate of the right-bottom corner. */ + // The x-coordinate of the right-bottom corner. float right; - /** @brief The y-coordinate of the right-bottom corner. */ + // The y-coordinate of the right-bottom corner. float bottom; - /**@}*/ } * FS_LPRECTF, FS_RECTF; -/** @brief Const Pointer to ::FS_RECTF structure.*/ + +// Const Pointer to FS_RECTF structure. typedef const FS_RECTF* FS_LPCRECTF; #if defined(_WIN32) && defined(FPDFSDK_EXPORTS) @@ -128,7 +126,7 @@ extern "C" { // backwards comatibility purposes. DLLEXPORT void STDCALL FPDF_InitLibrary(); -// Process-wide options for initializing library. +// Process-wide options for initializing the library. typedef struct FPDF_LIBRARY_CONFIG_ { // Version number of the interface. Currently must be 2. int version; @@ -154,7 +152,7 @@ typedef struct FPDF_LIBRARY_CONFIG_ { // Function: FPDF_InitLibraryWithConfig // Initialize the FPDFSDK library // Parameters: -// cfg - configuration information as above. +// config - configuration information as above. // Return value: // None. // Comments: @@ -172,8 +170,8 @@ DLLEXPORT void STDCALL FPDF_InitLibraryWithConfig( // Comments: // You can call this function to release all memory blocks allocated by // the library. -// After this function called, you should not call any PDF processing -// functions. +// After this function is called, you should not call any PDF +// processing functions. DLLEXPORT void STDCALL FPDF_DestroyLibrary(); // Policy for accessing the local machine time. @@ -182,9 +180,9 @@ DLLEXPORT void STDCALL FPDF_DestroyLibrary(); // Function: FPDF_SetSandBoxPolicy // Set the policy for the sandbox environment. // Parameters: -// policy - The specified policy for setting, for -// example:FPDF_POLICY_MACHINETIME_ACCESS. -// enable - True for enable, False for disable the policy. +// policy - The specified policy for setting, for example: +// FPDF_POLICY_MACHINETIME_ACCESS. +// enable - True to enable, false to disable the policy. // Return value: // None. DLLEXPORT void STDCALL FPDF_SetSandBoxPolicy(FPDF_DWORD policy, @@ -193,9 +191,9 @@ DLLEXPORT void STDCALL FPDF_SetSandBoxPolicy(FPDF_DWORD policy, // Function: FPDF_LoadDocument // Open and load a PDF document. // Parameters: -// file_path [in] - Path to the PDF file (including extension). -// password [in] - A string used as the password for PDF file. -// If no password needed, empty or NULL can be used. +// file_path - Path to the PDF file (including extension). +// password - A string used as the password for the PDF file. +// If no password is needed, empty or NULL can be used. // Return value: // A handle to the loaded document, or NULL on failure. // Comments: @@ -210,16 +208,15 @@ DLLEXPORT FPDF_DOCUMENT STDCALL FPDF_LoadDocument(FPDF_STRING file_path, // Parameters: // data_buf - Pointer to a buffer containing the PDF document. // size - Number of bytes in the PDF document. -// password - A string used as the password for PDF file. -// If no password needed, empty or NULL can be used. +// password - A string used as the password for the PDF file. +// If no password is needed, empty or NULL can be used. // Return value: -// A handle to the loaded document. If failed, NULL is returned. +// A handle to the loaded document, or NULL on failure. // Comments: // The memory buffer must remain valid when the document is open. -// Loaded document can be closed by FPDF_CloseDocument. +// The loaded document can be closed by FPDF_CloseDocument. // If this function fails, you can use FPDF_GetLastError() to retrieve -// the reason why it fails. -// +// the reason why it failed. DLLEXPORT FPDF_DOCUMENT STDCALL FPDF_LoadMemDocument(const void* data_buf, int size, FPDF_BYTESTRING password); @@ -229,47 +226,48 @@ typedef struct { // File length, in bytes. unsigned long m_FileLen; - // A function pointer for getting a block of data from specific position. - // Position is specified by byte offset from beginning of the file. - // The position and size will never go out range of file length. + // A function pointer for getting a block of data from a specific position. + // Position is specified by byte offset from the beginning of the file. + // The position and size will never go out of range of the file length. // It may be possible for FPDFSDK to call this function multiple times for - // same position. + // the same position. // Return value: should be non-zero if successful, zero for error. int (*m_GetBlock)(void* param, unsigned long position, unsigned char* pBuf, unsigned long size); - // A custom pointer for all implementation specific data. - // This pointer will be used as the first parameter to m_GetBlock callback. + // A custom pointer for all implementation specific data. This pointer will + // be used as the first parameter to the m_GetBlock callback. void* m_Param; } FPDF_FILEACCESS; // Function: FPDF_LoadCustomDocument // Load PDF document from a custom access descriptor. // Parameters: -// pFileAccess - A structure for access the file. +// pFileAccess - A structure for accessing the file. // password - Optional password for decrypting the PDF file. // Return value: -// A handle to the loaded document. If failed, NULL is returned. +// A handle to the loaded document, or NULL on failure. // Comments: -// The application should maintain the file resources being valid until -// the PDF document close. -// Loaded document can be closed by FPDF_CloseDocument. +// The application must keep the file resources valid until the PDF +// document is closed. +// +// The loaded document can be closed with FPDF_CloseDocument. DLLEXPORT FPDF_DOCUMENT STDCALL FPDF_LoadCustomDocument(FPDF_FILEACCESS* pFileAccess, FPDF_BYTESTRING password); // Function: FPDF_GetFileVersion -// Get the file version of the specific PDF document. +// Get the file version of the given PDF document. // Parameters: -// doc - Handle to document. +// doc - Handle to a document. // fileVersion - The PDF file version. File version: 14 for 1.4, 15 -// for 1.5, ... +// for 1.5, ... // Return value: -// TRUE if this call succeed, If failed, FALSE is returned. +// True if succeeds, false otherwise. // Comments: -// If the document is created by function ::FPDF_CreateNewDocument, -// then this function would always fail. +// If the document was created by FPDF_CreateNewDocument, +// then this function will always fail. DLLEXPORT FPDF_BOOL STDCALL FPDF_GetFileVersion(FPDF_DOCUMENT doc, int* fileVersion); @@ -282,156 +280,143 @@ DLLEXPORT FPDF_BOOL STDCALL FPDF_GetFileVersion(FPDF_DOCUMENT doc, #define FPDF_ERR_PAGE 6 // Page not found or content error. // Function: FPDF_GetLastError -// Get last error code when an SDK function failed. +// Get last error code when a function fails. // Parameters: // None. // Return value: -// A 32-bit integer indicating error codes (defined above). +// A 32-bit integer indicating error code as defined above. // Comments: // If the previous SDK call succeeded, the return value of this -// function -// is not defined. -// +// function is not defined. DLLEXPORT unsigned long STDCALL FPDF_GetLastError(); // Function: FPDF_GetDocPermission // Get file permission flags of the document. // Parameters: -// document - Handle to document. Returned by FPDF_LoadDocument -// function. +// document - Handle to a document. Returned by FPDF_LoadDocument. // Return value: -// A 32-bit integer indicating permission flags. Please refer to PDF -// Reference for -// detailed description. If the document is not protected, 0xffffffff -// will be returned. -// +// A 32-bit integer indicating permission flags. Please refer to the +// PDF Reference for detailed descriptions. If the document is not +// protected, 0xffffffff will be returned. DLLEXPORT unsigned long STDCALL FPDF_GetDocPermissions(FPDF_DOCUMENT document); // Function: FPDF_GetSecurityHandlerRevision -// Get the revision for security handler. +// Get the revision for the security handler. // Parameters: -// document - Handle to document. Returned by FPDF_LoadDocument -// function. +// document - Handle to a document. Returned by FPDF_LoadDocument. // Return value: -// The security handler revision number. Please refer to PDF Reference -// for -// detailed description. If the document is not protected, -1 will be -// returned. -// +// The security handler revision number. Please refer to the PDF +// Reference for a detailed description. If the document is not +// protected, -1 will be returned. DLLEXPORT int STDCALL FPDF_GetSecurityHandlerRevision(FPDF_DOCUMENT document); // Function: FPDF_GetPageCount -// Get total number of pages in a document. +// Get total number of pages in the document. // Parameters: -// document - Handle to document. Returned by FPDF_LoadDocument -// function. +// document - Handle to document. Returned by FPDF_LoadDocument. // Return value: // Total number of pages in the document. -// DLLEXPORT int STDCALL FPDF_GetPageCount(FPDF_DOCUMENT document); // Function: FPDF_LoadPage -// Load a page inside a document. +// Load a page inside the document. // Parameters: // document - Handle to document. Returned by FPDF_LoadDocument -// function. // page_index - Index number of the page. 0 for the first page. // Return value: -// A handle to the loaded page. If failed, NULL is returned. +// A handle to the loaded page, or NULL if page load fails. // Comments: -// Loaded page can be rendered to devices using FPDF_RenderPage -// function. -// Loaded page can be closed by FPDF_ClosePage. -// +// The loaded page can be rendered to devices using FPDF_RenderPage. +// The loaded page can be closed using FPDF_ClosePage. DLLEXPORT FPDF_PAGE STDCALL FPDF_LoadPage(FPDF_DOCUMENT document, int page_index); // Function: FPDF_GetPageWidth // Get page width. // Parameters: -// page - Handle to the page. Returned by FPDF_LoadPage -// function. +// page - Handle to the page. Returned by FPDF_LoadPage. // Return value: // Page width (excluding non-displayable area) measured in points. // One point is 1/72 inch (around 0.3528 mm). -// DLLEXPORT double STDCALL FPDF_GetPageWidth(FPDF_PAGE page); // Function: FPDF_GetPageHeight // Get page height. // Parameters: -// page - Handle to the page. Returned by FPDF_LoadPage -// function. +// page - Handle to the page. Returned by FPDF_LoadPage. // Return value: // Page height (excluding non-displayable area) measured in points. // One point is 1/72 inch (around 0.3528 mm) -// DLLEXPORT double STDCALL FPDF_GetPageHeight(FPDF_PAGE page); // Function: FPDF_GetPageSizeByIndex -// Get the size of a page by index. +// Get the size of the page at the given index. // Parameters: -// document - Handle to document. Returned by FPDF_LoadDocument -// function. +// document - Handle to document. Returned by FPDF_LoadDocument. // page_index - Page index, zero for the first page. -// width - Pointer to a double value receiving the page width -// (in points). -// height - Pointer to a double value receiving the page height -// (in points). +// width - Pointer to a double to receive the page width +// (in points). +// height - Pointer to a double to receive the page height +// (in points). // Return value: // Non-zero for success. 0 for error (document or page not found). -// DLLEXPORT int STDCALL FPDF_GetPageSizeByIndex(FPDF_DOCUMENT document, int page_index, double* width, double* height); -// Page rendering flags. They can be combined with bit OR. -#define FPDF_ANNOT 0x01 // Set if annotations are to be rendered. -#define FPDF_LCD_TEXT \ - 0x02 // Set if using text rendering optimized for LCD display. -#define FPDF_NO_NATIVETEXT \ - 0x04 // Don't use the native text output available on some platforms -#define FPDF_GRAYSCALE 0x08 // Grayscale output. -#define FPDF_DEBUG_INFO 0x80 // Set if you want to get some debug info. -// Please discuss with Foxit first if you need to collect debug info. -#define FPDF_NO_CATCH 0x100 // Set if you don't want to catch exception. -#define FPDF_RENDER_LIMITEDIMAGECACHE 0x200 // Limit image cache size. -#define FPDF_RENDER_FORCEHALFTONE \ - 0x400 // Always use halftone for image stretching. -#define FPDF_PRINTING 0x800 // Render for printing. -#define FPDF_RENDER_NO_SMOOTHTEXT \ - 0x1000 // Set to disable anti-aliasing on text. -#define FPDF_RENDER_NO_SMOOTHIMAGE \ - 0x2000 // Set to disable anti-aliasing on images. -#define FPDF_RENDER_NO_SMOOTHPATH \ - 0x4000 // Set to disable anti-aliasing on paths. -#define FPDF_REVERSE_BYTE_ORDER \ - 0x10 // set whether render in a reverse Byte order, this flag only -// enable when render to a bitmap. +// Page rendering flags. They can be combined with bit-wise OR. +// +// Set if annotations are to be rendered. +#define FPDF_ANNOT 0x01 +// Set if using text rendering optimized for LCD display. +#define FPDF_LCD_TEXT 0x02 +// Don't use the native text output available on some platforms +#define FPDF_NO_NATIVETEXT 0x04 +// Grayscale output. +#define FPDF_GRAYSCALE 0x08 +// Set if you want to get some debug info. +#define FPDF_DEBUG_INFO 0x80 +// Set if you don't want to catch exceptions. +#define FPDF_NO_CATCH 0x100 +// Limit image cache size. +#define FPDF_RENDER_LIMITEDIMAGECACHE 0x200 +// Always use halftone for image stretching. +#define FPDF_RENDER_FORCEHALFTONE 0x400 +// Render for printing. +#define FPDF_PRINTING 0x800 +// Set to disable anti-aliasing on text. +#define FPDF_RENDER_NO_SMOOTHTEXT 0x1000 +// Set to disable anti-aliasing on images. +#define FPDF_RENDER_NO_SMOOTHIMAGE 0x2000 +// Set to disable anti-aliasing on paths. +#define FPDF_RENDER_NO_SMOOTHPATH 0x4000 +// Set whether to render in a reverse Byte order, this flag is only used when +// rendering to a bitmap. +#define FPDF_REVERSE_BYTE_ORDER 0x10 + #ifdef _WIN32 // Function: FPDF_RenderPage -// Render contents in a page to a device (screen, bitmap, or printer). -// This function is only supported on Windows system. -// Parameters: -// dc - Handle to device context. -// page - Handle to the page. Returned by FPDF_LoadPage -// function. -// start_x - Left pixel position of the display area in the -// device coordinate. -// start_y - Top pixel position of the display area in the device -// coordinate. +// Render contents of a page to a device (screen, bitmap, or printer). +// This function is only supported on Windows. +// Parameters: +// dc - Handle to the device context. +// page - Handle to the page. Returned by FPDF_LoadPage. +// start_x - Left pixel position of the display area in +// device coordinates. +// start_y - Top pixel position of the display area in device +// coordinates. // size_x - Horizontal size (in pixels) for displaying the page. // size_y - Vertical size (in pixels) for displaying the page. -// rotate - Page orientation: 0 (normal), 1 (rotated 90 degrees -// clockwise), -// 2 (rotated 180 degrees), 3 (rotated 90 degrees -// counter-clockwise). +// rotate - Page orientation: +// 0 (normal) +// 1 (rotated 90 degrees clockwise) +// 2 (rotated 180 degrees) +// 3 (rotated 90 degrees counter-clockwise) // flags - 0 for normal display, or combination of flags -// defined above. +// defined above. // Return value: // None. -// DLLEXPORT void STDCALL FPDF_RenderPage(HDC dc, FPDF_PAGE page, int start_x, @@ -443,29 +428,27 @@ DLLEXPORT void STDCALL FPDF_RenderPage(HDC dc, #endif // Function: FPDF_RenderPageBitmap -// Render contents in a page to a device independent bitmap +// Render contents of a page to a device independent bitmap. // Parameters: // bitmap - Handle to the device independent bitmap (as the -// output buffer). -// Bitmap handle can be created by FPDFBitmap_Create -// function. +// output buffer). The bitmap handle can be created +// by FPDFBitmap_Create. // page - Handle to the page. Returned by FPDF_LoadPage -// function. -// start_x - Left pixel position of the display area in the -// bitmap coordinate. -// start_y - Top pixel position of the display area in the bitmap -// coordinate. +// start_x - Left pixel position of the display area in +// bitmap coordinates. +// start_y - Top pixel position of the display area in bitmap +// coordinates. // size_x - Horizontal size (in pixels) for displaying the page. // size_y - Vertical size (in pixels) for displaying the page. -// rotate - Page orientation: 0 (normal), 1 (rotated 90 degrees -// clockwise), -// 2 (rotated 180 degrees), 3 (rotated 90 degrees -// counter-clockwise). +// rotate - Page orientation: +// 0 (normal) +// 1 (rotated 90 degrees clockwise) +// 2 (rotated 180 degrees) +// 3 (rotated 90 degrees counter-clockwise) // flags - 0 for normal display, or combination of flags -// defined above. +// defined above. // Return value: // None. -// DLLEXPORT void STDCALL FPDF_RenderPageBitmap(FPDF_BITMAP bitmap, FPDF_PAGE page, int start_x, @@ -481,7 +464,6 @@ DLLEXPORT void STDCALL FPDF_RenderPageBitmap(FPDF_BITMAP bitmap, // page - Handle to the loaded page. // Return value: // None. -// DLLEXPORT void STDCALL FPDF_ClosePage(FPDF_PAGE page); // Function: FPDF_CloseDocument @@ -490,51 +472,48 @@ DLLEXPORT void STDCALL FPDF_ClosePage(FPDF_PAGE page); // document - Handle to the loaded document. // Return value: // None. -// DLLEXPORT void STDCALL FPDF_CloseDocument(FPDF_DOCUMENT document); // Function: FPDF_DeviceToPage -// Convert the screen coordinate of a point to page coordinate. +// Convert the screen coordinates of a point to page coordinates. // Parameters: -// page - Handle to the page. Returned by FPDF_LoadPage -// function. -// start_x - Left pixel position of the display area in the -// device coordinate. -// start_y - Top pixel position of the display area in the device -// coordinate. +// page - Handle to the page. Returned by FPDF_LoadPage. +// start_x - Left pixel position of the display area in +// device coordinates. +// start_y - Top pixel position of the display area in device +// coordinates. // size_x - Horizontal size (in pixels) for displaying the page. // size_y - Vertical size (in pixels) for displaying the page. -// rotate - Page orientation: 0 (normal), 1 (rotated 90 degrees -// clockwise), -// 2 (rotated 180 degrees), 3 (rotated 90 degrees -// counter-clockwise). -// device_x - X value in device coordinate, for the point to be -// converted. -// device_y - Y value in device coordinate, for the point to be -// converted. -// page_x - A Pointer to a double receiving the converted X -// value in page coordinate. -// page_y - A Pointer to a double receiving the converted Y -// value in page coordinate. +// rotate - Page orientation: +// 0 (normal) +// 1 (rotated 90 degrees clockwise) +// 2 (rotated 180 degrees) +// 3 (rotated 90 degrees counter-clockwise) +// device_x - X value in device coordinates to be converted. +// device_y - Y value in device coordinates to be converted. +// page_x - A pointer to a double receiving the converted X +// value in page coordinates. +// page_y - A pointer to a double receiving the converted Y +// value in page coordinates. // Return value: // None. // Comments: -// The page coordinate system has its origin at left-bottom corner of -// the page, with X axis goes along -// the bottom side to the right, and Y axis goes along the left side -// upward. NOTE: this coordinate system -// can be altered when you zoom, scroll, or rotate a page, however, a -// point on the page should always have +// The page coordinate system has its origin at the left-bottom corner +// of the page, with the X-axis on the bottom going to the right, and +// the Y-axis on the left side going up. +// +// NOTE: this coordinate system can be altered when you zoom, scroll, +// or rotate a page, however, a point on the page should always have // the same coordinate values in the page coordinate system. // // The device coordinate system is device dependent. For screen device, -// its origin is at left-top -// corner of the window. However this origin can be altered by Windows -// coordinate transformation -// utilities. You must make sure the start_x, start_y, size_x, size_y -// and rotate parameters have exactly -// same values as you used in FPDF_RenderPage() function call. +// its origin is at the left-top corner of the window. However this +// origin can be altered by the Windows coordinate transformation +// utilities. // +// You must make sure the start_x, start_y, size_x, size_y +// and rotate parameters have exactly same values as you used in +// the FPDF_RenderPage() function call. DLLEXPORT void STDCALL FPDF_DeviceToPage(FPDF_PAGE page, int start_x, int start_y, @@ -547,33 +526,30 @@ DLLEXPORT void STDCALL FPDF_DeviceToPage(FPDF_PAGE page, double* page_y); // Function: FPDF_PageToDevice -// Convert the page coordinate of a point to screen coordinate. +// Convert the page coordinates of a point to screen coordinates. // Parameters: -// page - Handle to the page. Returned by FPDF_LoadPage -// function. -// start_x - Left pixel position of the display area in the -// device coordinate. -// start_y - Top pixel position of the display area in the device -// coordinate. +// page - Handle to the page. Returned by FPDF_LoadPage. +// start_x - Left pixel position of the display area in +// device coordinates. +// start_y - Top pixel position of the display area in device +// coordinates. // size_x - Horizontal size (in pixels) for displaying the page. // size_y - Vertical size (in pixels) for displaying the page. -// rotate - Page orientation: 0 (normal), 1 (rotated 90 degrees -// clockwise), -// 2 (rotated 180 degrees), 3 (rotated 90 degrees -// counter-clockwise). -// page_x - X value in page coordinate, for the point to be -// converted. -// page_y - Y value in page coordinate, for the point to be -// converted. -// device_x - A pointer to an integer receiving the result X value -// in device coordinate. -// device_y - A pointer to an integer receiving the result Y value -// in device coordinate. +// rotate - Page orientation: +// 0 (normal) +// 1 (rotated 90 degrees clockwise) +// 2 (rotated 180 degrees) +// 3 (rotated 90 degrees counter-clockwise) +// page_x - X value in page coordinates. +// page_y - Y value in page coordinate. +// device_x - A pointer to an integer receiving the result X +// value in device coordinates. +// device_y - A pointer to an integer receiving the result Y +// value in device coordinates. // Return value: // None. // Comments: -// See comments of FPDF_DeviceToPage() function. -// +// See comments for FPDF_DeviceToPage(). DLLEXPORT void STDCALL FPDF_PageToDevice(FPDF_PAGE page, int start_x, int start_y, @@ -586,79 +562,73 @@ DLLEXPORT void STDCALL FPDF_PageToDevice(FPDF_PAGE page, int* device_y); // Function: FPDFBitmap_Create -// Create a Foxit Device Independent Bitmap (FXDIB). +// Create a device independent bitmap (FXDIB). // Parameters: -// width - Number of pixels in a horizontal line of the bitmap. -// Must be greater than 0. -// height - Number of pixels in a vertical line of the bitmap. -// Must be greater than 0. -// alpha - A flag indicating whether alpha channel is used. -// Non-zero for using alpha, zero for not using. +// width - The number of pixels in width for the bitmap. +// Must be greater than 0. +// height - The number of pixels in height for the bitmap. +// Must be greater than 0. +// alpha - A flag indicating whether the alpha channel is used. +// Non-zero for using alpha, zero for not using. // Return value: -// The created bitmap handle, or NULL if parameter error or out of +// The created bitmap handle, or NULL if a parameter error or out of // memory. // Comments: -// An FXDIB always use 4 byte per pixel. The first byte of a pixel is -// always double word aligned. -// Each pixel contains red (R), green (G), blue (B) and optionally -// alpha (A) values. +// The bitmap always uses 4 bytes per pixel. The first byte is always +// double word aligned. +// // The byte order is BGRx (the last byte unused if no alpha channel) or // BGRA. // -// The pixels in a horizontal line (also called scan line) are stored -// side by side, with left most -// pixel stored first (with lower memory address). Each scan line uses -// width*4 bytes. +// The pixels in a horizontal line are stored side by side, with the +// left most pixel stored first (with lower memory address). +// Each line uses width * 4 bytes. // -// Scan lines are stored one after another, with top most scan line -// stored first. There is no gap -// between adjacent scan lines. +// Lines are stored one after another, with the top most line stored +// first. There is no gap between adjacent lines. // // This function allocates enough memory for holding all pixels in the -// bitmap, but it doesn't -// initialize the buffer. Applications can use FPDFBitmap_FillRect to -// fill the bitmap using any color. +// bitmap, but it doesn't initialize the buffer. Applications can use +// FPDFBitmap_FillRect to fill the bitmap using any color. DLLEXPORT FPDF_BITMAP STDCALL FPDFBitmap_Create(int width, int height, int alpha); // More DIB formats -#define FPDFBitmap_Gray 1 // Gray scale bitmap, one byte per pixel. -#define FPDFBitmap_BGR 2 // 3 bytes per pixel, byte order: blue, green, red. -#define FPDFBitmap_BGRx \ - 3 // 4 bytes per pixel, byte order: blue, green, red, unused. -#define FPDFBitmap_BGRA \ - 4 // 4 bytes per pixel, byte order: blue, green, red, alpha. +// Gray scale bitmap, one byte per pixel. +#define FPDFBitmap_Gray 1 +// 3 bytes per pixel, byte order: blue, green, red. +#define FPDFBitmap_BGR 2 +// 4 bytes per pixel, byte order: blue, green, red, unused. +#define FPDFBitmap_BGRx 3 +// 4 bytes per pixel, byte order: blue, green, red, alpha. +#define FPDFBitmap_BGRA 4 // Function: FPDFBitmap_CreateEx -// Create a Foxit Device Independent Bitmap (FXDIB) +// Create a device independent bitmap (FXDIB) // Parameters: -// width - Number of pixels in a horizontal line of the bitmap. -// Must be greater than 0. -// height - Number of pixels in a vertical line of the bitmap. -// Must be greater than 0. +// width - The number of pixels in width for the bitmap. +// Must be greater than 0. +// height - The number of pixels in height for the bitmap. +// Must be greater than 0. // format - A number indicating for bitmap format, as defined -// above. -// first_scan - A pointer to the first byte of first scan line, for -// external buffer -// only. If this parameter is NULL, then the SDK will -// create its own buffer. +// above. +// first_scan - A pointer to the first byte of the first line if +// using an external buffer. If this parameter is NULL, +// then the a new buffer will be created. // stride - Number of bytes for each scan line, for external -// buffer only.. +// buffer only. // Return value: -// The created bitmap handle, or NULL if parameter error or out of -// memory. +// The bitmap handle, or NULL if parameter error or out of memory. // Comments: -// Similar to FPDFBitmap_Create function, with more formats and -// external buffer supported. -// Bitmap created by this function can be used in any place that a -// FPDF_BITMAP handle is +// Similar to FPDFBitmap_Create function, but allows for more formats +// and an external buffer is supported. The bitmap created by this +// function can be used in any place that a FPDF_BITMAP handle is // required. // -// If external scanline buffer is used, then the application should -// destroy the buffer -// by itself. FPDFBitmap_Destroy function will not destroy the buffer. -// +// If an external buffer is used, then the application should destroy +// the buffer by itself. FPDFBitmap_Destroy function will not destroy +// the buffer. DLLEXPORT FPDF_BITMAP STDCALL FPDFBitmap_CreateEx(int width, int height, int format, @@ -666,29 +636,29 @@ DLLEXPORT FPDF_BITMAP STDCALL FPDFBitmap_CreateEx(int width, int stride); // Function: FPDFBitmap_FillRect -// Fill a rectangle area in an FXDIB. +// Fill a rectangle in a bitmap. // Parameters: // bitmap - The handle to the bitmap. Returned by -// FPDFBitmap_Create function. -// left - The left side position. Starting from 0 at the -// left-most pixel. -// top - The top side position. Starting from 0 at the -// top-most scan line. -// width - Number of pixels to be filled in each scan line. -// height - Number of scan lines to be filled. +// FPDFBitmap_Create. +// left - The left position. Starting from 0 at the +// left-most pixel. +// top - The top position. Starting from 0 at the +// top-most line. +// width - Width in pixels to be filled. +// height - Height in pixels to be filled. // color - A 32-bit value specifing the color, in 8888 ARGB -// format. +// format. // Return value: // None. // Comments: -// This function set the color and (optionally) alpha value in +// This function sets the color and (optionally) alpha value in the // specified region of the bitmap. -// NOTE: If alpha channel is used, this function does NOT composite the -// background with the source color, -// instead the background will be replaced by the source color and -// alpha. -// If alpha channel is not used, the "alpha" parameter is ignored. // +// NOTE: If the alpha channel is used, this function does NOT +// composite the background with the source color, instead the +// background will be replaced by the source color and the alpha. +// +// If the alpha channel is not used, the alpha parameter is ignored. DLLEXPORT void STDCALL FPDFBitmap_FillRect(FPDF_BITMAP bitmap, int left, int top, @@ -697,58 +667,57 @@ DLLEXPORT void STDCALL FPDFBitmap_FillRect(FPDF_BITMAP bitmap, FPDF_DWORD color); // Function: FPDFBitmap_GetBuffer -// Get data buffer of an FXDIB +// Get data buffer of a bitmap. // Parameters: -// bitmap - Handle to the bitmap. Returned by FPDFBitmap_Create -// function. +// bitmap - Handle to the bitmap. Returned by FPDFBitmap_Create. // Return value: // The pointer to the first byte of the bitmap buffer. // Comments: // The stride may be more than width * number of bytes per pixel +// // Applications can use this function to get the bitmap buffer pointer, -// then manipulate any color -// and/or alpha values for any pixels in the bitmap. +// then manipulate any color and/or alpha values for any pixels in the +// bitmap. +// +// The data is in BGRA format. Where the A maybe unused if alpha was +// not specified. DLLEXPORT void* STDCALL FPDFBitmap_GetBuffer(FPDF_BITMAP bitmap); // Function: FPDFBitmap_GetWidth -// Get width of an FXDIB. +// Get width of a bitmap. // Parameters: -// bitmap - Handle to the bitmap. Returned by FPDFBitmap_Create -// function. +// bitmap - Handle to the bitmap. Returned by FPDFBitmap_Create. // Return value: -// The number of pixels in a horizontal line of the bitmap. +// The width of the bitmap in pixels. DLLEXPORT int STDCALL FPDFBitmap_GetWidth(FPDF_BITMAP bitmap); // Function: FPDFBitmap_GetHeight -// Get height of an FXDIB. +// Get height of a bitmap. // Parameters: -// bitmap - Handle to the bitmap. Returned by FPDFBitmap_Create -// function. +// bitmap - Handle to the bitmap. Returned by FPDFBitmap_Create. // Return value: -// The number of pixels in a vertical line of the bitmap. +// The height of the bitmap in pixels. DLLEXPORT int STDCALL FPDFBitmap_GetHeight(FPDF_BITMAP bitmap); // Function: FPDFBitmap_GetStride -// Get number of bytes for each scan line in the bitmap buffer. +// Get number of bytes for each line in the bitmap buffer. // Parameters: -// bitmap - Handle to the bitmap. Returned by FPDFBitmap_Create -// function. +// bitmap - Handle to the bitmap. Returned by FPDFBitmap_Create. // Return value: -// The number of bytes for each scan line in the bitmap buffer. +// The number of bytes for each line in the bitmap buffer. // Comments: -// The stride may be more than width * number of bytes per pixel +// The stride may be more than width * number of bytes per pixel. DLLEXPORT int STDCALL FPDFBitmap_GetStride(FPDF_BITMAP bitmap); // Function: FPDFBitmap_Destroy -// Destroy an FXDIB and release all related buffers. +// Destroy a bitmap and release all related buffers. // Parameters: -// bitmap - Handle to the bitmap. Returned by FPDFBitmap_Create -// function. +// bitmap - Handle to the bitmap. Returned by FPDFBitmap_Create. // Return value: // None. // Comments: -// This function will not destroy any external buffer. -// +// This function will not destroy any external buffers provided when +// the bitmap was created. DLLEXPORT void STDCALL FPDFBitmap_Destroy(FPDF_BITMAP bitmap); // Function: FPDF_VIEWERREF_GetPrintScaling @@ -757,7 +726,6 @@ DLLEXPORT void STDCALL FPDFBitmap_Destroy(FPDF_BITMAP bitmap); // document - Handle to the loaded document. // Return value: // None. -// DLLEXPORT FPDF_BOOL STDCALL FPDF_VIEWERREF_GetPrintScaling(FPDF_DOCUMENT document); @@ -767,7 +735,6 @@ FPDF_VIEWERREF_GetPrintScaling(FPDF_DOCUMENT document); // document - Handle to the loaded document. // Return value: // The number of copies to be printed. -// DLLEXPORT int STDCALL FPDF_VIEWERREF_GetNumCopies(FPDF_DOCUMENT document); // Function: FPDF_VIEWERREF_GetPrintPageRange @@ -776,18 +743,16 @@ DLLEXPORT int STDCALL FPDF_VIEWERREF_GetNumCopies(FPDF_DOCUMENT document); // document - Handle to the loaded document. // Return value: // The print page range to be used for printing. -// DLLEXPORT FPDF_PAGERANGE STDCALL FPDF_VIEWERREF_GetPrintPageRange(FPDF_DOCUMENT document); // Function: FPDF_VIEWERREF_GetDuplex // Returns the paper handling option to be used when printing from -// print dialog. +// the print dialog. // Parameters: // document - Handle to the loaded document. // Return value: // The paper handling option to be used when printing. -// DLLEXPORT FPDF_DUPLEXTYPE STDCALL FPDF_VIEWERREF_GetDuplex(FPDF_DOCUMENT document); @@ -800,36 +765,36 @@ FPDF_VIEWERREF_GetDuplex(FPDF_DOCUMENT document); DLLEXPORT FPDF_DWORD STDCALL FPDF_CountNamedDests(FPDF_DOCUMENT document); // Function: FPDF_GetNamedDestByName -// get a special dest handle by the index. +// Get a the destination handle for the given name. // Parameters: // document - Handle to the loaded document. -// name - The name of a special named dest. +// name - The name of a destination. // Return value: -// The handle of the dest. -// +// The handle to the destination. DLLEXPORT FPDF_DEST STDCALL FPDF_GetNamedDestByName(FPDF_DOCUMENT document, FPDF_BYTESTRING name); // Function: FPDF_GetNamedDest -// Get the specified named destinations of the PDF document by index. +// Get the named destination by index. // Parameters: // document - Handle to a document -// index - The index of named destination. -// buffer - The buffer to obtain destination name, used as -// wchar_t*. -// buflen [in/out] - Size of the buffer in bytes on input, length of -// the result in bytes on output or -1 if the buffer is too small. -// Return value: -// The destination handle of a named destination, or NULL if no named -// destination corresponding to |index|. +// index - The index of a named destination. +// buffer - The buffer to store the destination name, +// used as wchar_t*. +// buflen [in/out] - Size of the buffer in bytes on input, +// length of the result in bytes on output +// or -1 if the buffer is too small. +// Return value: +// The destination handle for a given index, or NULL if there is no +// named destination corresponding to |index|. // Comments: // Call this function twice to get the name of the named destination: -// 1) First time pass in |buffer| as NULL and get buflen. -// 2) Second time pass in allocated |buffer| and buflen to retrieve -// |buffer|, which should be used as wchar_t*. -// If buflen is not sufficiently large, it will be set to -1 upon -// return. +// 1) First time pass in |buffer| as NULL and get buflen. +// 2) Second time pass in allocated |buffer| and buflen to retrieve +// |buffer|, which should be used as wchar_t*. // +// If buflen is not sufficiently large, it will be set to -1 upon +// return. DLLEXPORT FPDF_DEST STDCALL FPDF_GetNamedDest(FPDF_DOCUMENT document, int index, void* buffer, |