Chromium Code Reviews Chromium Code Reviews
Issue 1411863004:
Minor documentation updates for fpdfview.h. (Closed)
Base URL: https://pdfium.googlesource.com/pdfium.git@master| Index: public/fpdfview.h |
| diff --git a/public/fpdfview.h b/public/fpdfview.h |
| index ea45c2912ce25f224652ca0fe369655de333e340..ba7854609632cdbdaee746ab2495131b2ab74088 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 string, each character uses 2 |
|
Tom Sepez
2015/10/20 16:29:49
nit: uses ... wide strings (plural)
dsinclair
2015/10/20 16:52:29
Done.
|
| +// 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 |
| +// Windows unicode string, however, special care needs to be taken if you |
|
Tom Sepez
2015/10/20 16:29:49
nit: as a Windows (add "a").
dsinclair
2015/10/20 16:52:29
Done.
|
| +// expect to process Unicode larger than 0xffff. |
| +// |
| +// For Linux/Unix programmers: most compiler/library environments use 4 bytes |
| +// for a Unicode character, you have to convert between FPDF_WIDESTRING and |
|
Tom Sepez
2015/10/20 16:29:49
nit: , and you [or change , to a ; ]
dsinclair
2015/10/20 16:52:28
Done.
|
| +// system wide string by yourself. |
| #ifdef _WIN32_WCE |
| typedef const unsigned short* FPDF_STRING; |
| @@ -87,7 +86,7 @@ typedef struct _FS_MATRIX_ { |
| float f; /**< @brief Coefficient f.*/ |
| } FS_MATRIX; |
| -/** @brief Rectangle area(float) in device or page coordination system. */ |
| +/** @brief Rectangle area(float) in device or page coordinate system. */ |
| typedef struct _FS_RECTF_ { |
| /**@{*/ |
| /** @brief The x-coordinate of the left-top corner. */ |
| @@ -128,7 +127,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 +153,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 +171,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 +181,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. |
|
Tom Sepez
2015/10/20 16:29:49
nit: no need to capitalize False.
dsinclair
2015/10/20 16:52:28
Done.
|
| // Return value: |
| // None. |
| DLLEXPORT void STDCALL FPDF_SetSandBoxPolicy(FPDF_DWORD policy, |
| @@ -193,9 +192,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 +209,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,46 +227,46 @@ 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 application should maintain the file resources until |
|
Tom Sepez
2015/10/20 16:29:49
nit: The application must keep the file resources
dsinclair
2015/10/20 16:52:28
Done.
|
| // the PDF document close. |
| // Loaded document can be closed by 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 this call succeeds. |
|
Tom Sepez
2015/10/20 16:29:49
nit: succeeds, false otherwise.
dsinclair
2015/10/20 16:52:28
Done.
|
| // Comments: |
| -// If the document is created by function ::FPDF_CreateNewDocument, |
| +// If the document is created by ::FPDF_CreateNewDocument, |
|
Tom Sepez
2015/10/20 16:29:49
nit: lose the ::, "was created by"
dsinclair
2015/10/20 16:52:28
Done.
|
| // then this function would always fail. |
|
Tom Sepez
2015/10/20 16:29:49
nit: will always
dsinclair
2015/10/20 16:52:28
Done.
|
| DLLEXPORT FPDF_BOOL STDCALL FPDF_GetFileVersion(FPDF_DOCUMENT doc, |
| int* fileVersion); |
| @@ -282,111 +280,92 @@ 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. |
| +// Page rendering flags. They can be combined with bit-wise OR. |
| #define FPDF_ANNOT 0x01 // Set if annotations are to be rendered. |
|
Tom Sepez
2015/10/20 16:29:49
nit: (super-nit) can we get these each to fit on a
dsinclair
2015/10/20 16:52:28
Done.
|
| #define FPDF_LCD_TEXT \ |
| 0x02 // Set if using text rendering optimized for LCD display. |
| @@ -394,8 +373,7 @@ DLLEXPORT int STDCALL FPDF_GetPageSizeByIndex(FPDF_DOCUMENT document, |
| 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_NO_CATCH 0x100 // Set if you don't want to catch exceptions. |
| #define FPDF_RENDER_LIMITEDIMAGECACHE 0x200 // Limit image cache size. |
| #define FPDF_RENDER_FORCEHALFTONE \ |
| 0x400 // Always use halftone for image stretching. |
| @@ -407,31 +385,31 @@ DLLEXPORT int STDCALL FPDF_GetPageSizeByIndex(FPDF_DOCUMENT document, |
| #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. |
| + 0x10 // set whether to render in a reverse Byte order, this flag is only |
| + // used when rendering to a bitmap. |
| + |
| #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 +421,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 +457,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 +465,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 +519,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,38 +555,34 @@ 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); |
| @@ -631,34 +596,30 @@ DLLEXPORT FPDF_BITMAP STDCALL FPDFBitmap_Create(int width, |
| 4 // 4 bytes per pixel, byte order: blue, green, red, alpha. |
| // 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, bug allows for more formats |
|
Tom Sepez
2015/10/20 16:29:49
but allows [ :). ]
dsinclair
2015/10/20 16:52:28
Done.
|
| +// 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 +627,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 +658,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 +717,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 +726,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 +734,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 +756,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, |
