Define behaviors of FPDF_RenderPageBitmap_Retail and FPDF_FFLDraw.chromium/2858chromium/2857chromium/2856

Previously, PDFium only supported widget annotations to draw forms. As
we've implemented other annotations, the behavior of
FPDF_RenderPageBitmap_Retail and FPDF_FFLDraw changed. So, this CL
clearly defines what needs to be done in FPDF_RenderPageBitmap_Retail
and FPDF_FFLDraw.

This CL first assumes that PDFium users will always call
FPDF_RenderPageBitmap_Retail and FPDF_FFLDraw to render PDF pages,
because otherwise they are not able to support PDF forms.

FPDF_RenderPageBitmap_Retail should only deal with non-widget
annotations, such as highlight, underline, text, etc. If
FPDF_ANNOT flag is passed, non-widget annotations are drawn. Otherwise,
they are hidden.

FPDF_FFLDraw should only deal with annotations that requires
user-interaction, such as widget annotations and popup annotation. Since
popup annotation is associated with non-widget annotation, they should
not be drawn if the associated annotation is hidden. Thus, if FPDF_ANNOT
flag is passed, popup annotations are drawn. Otherwise, they are hidden.
Widget annotations should be always drawn regardless of FPDF_ANNOT flag
since they need to be always displayed for PDF forms.

Also, roll DEPS for testing/corpus to 8485b30.

BUG=pdfium:594

Review-Url: https://codereview.chromium.org/2323203002

3 files changed, 19 insertions, 10 deletions

diff --git a/public/fpdf_formfill.h b/public/fpdf_formfill.h
index 248bcd2b02..09674b007c 100644
--- a/public/fpdf_formfill.h
+++ b/public/fpdf_formfill.h
@@ -1483,7 +1483,8 @@ DLLEXPORT void STDCALL FPDF_RemoveFormFieldHighlight(FPDF_FORMHANDLE hHandle);
 
 /**
 * Function: FPDF_FFLDraw
-*           Render FormFeilds on a page to a device independent bitmap.
+*           Render FormFields and popup window on a page to a device independent
+*bitmap.
 * Parameters:
 *           hHandle     -   Handle to the form fill module. Returned by
 *FPDFDOC_InitFormFillEnvironment.
@@ -1508,13 +1509,15 @@ DLLEXPORT void STDCALL FPDF_RemoveFormFieldHighlight(FPDF_FORMHANDLE hHandle);
 * Return Value:
 *           None.
 * Comments:
-*           This method is designed to only render annotations and FormFields on
-*the page.
-*           Without FPDF_ANNOT specified for flags, Rendering functions such as
-*FPDF_RenderPageBitmap or FPDF_RenderPageBitmap_Start will only render page
-*contents(without annotations) to a bitmap.
-*           In order to implement the FormFill functions,Implementation should
-*call this method after rendering functions finish rendering the page contents.
+*           This function is designed to render annotations that are
+*user-interactive, which are widget annotation (for FormFields) and popup
+*annotation.
+*           With FPDF_ANNOT flag, this function will render popup annotation
+*when users mouse-hover on non-widget annotation. Regardless of FPDF_ANNOT flag,
+*this function will always render widget annotations for FormFields.
+*           In order to implement the FormFill functions, implementation should
+*call this function after rendering functions, such as FPDF_RenderPageBitmap or
+*FPDF_RenderPageBitmap_Start, finish rendering the page contents.
 **/
 DLLEXPORT void STDCALL FPDF_FFLDraw(FPDF_FORMHANDLE hHandle,
                                     FPDF_BITMAP bitmap,
diff --git a/public/fpdf_progressive.h b/public/fpdf_progressive.h
index f352ff9d00..ffc812df77 100644
--- a/public/fpdf_progressive.h
+++ b/public/fpdf_progressive.h
@@ -66,7 +66,10 @@ typedef struct _IFSDK_PAUSE {
 //                              2 (rotated 180 degrees), 3 (rotated 90 degrees
 //                              counter-clockwise).
 //          flags       -   0 for normal display, or combination of flags
-//          defined above.
+//                          defined in fpdfview.h. With FPDF_ANNOT flag, it
+//                          renders all annotations that does not require
+//                          user-interaction, which are all annotations except
+//                          widget and popup annotations.
 //          pause       -   The IFSDK_PAUSE interface.A callback mechanism
 //          allowing the page rendering process
 // Return value:
diff --git a/public/fpdfview.h b/public/fpdfview.h
index cbb577b2fd..499124d6e8 100644
--- a/public/fpdfview.h
+++ b/public/fpdfview.h
@@ -595,7 +595,10 @@ DLLEXPORT void STDCALL FPDF_RenderPage(HDC dc,
 //                            2 (rotated 180 degrees)
 //                            3 (rotated 90 degrees counter-clockwise)
 //          flags       -   0 for normal display, or combination of flags
-//                          defined above.
+//                          defined above. With FPDF_ANNOT flag, it renders all
+//                          annotations that does not require user-interaction,
+//                          which are all annotations except widget and popup
+//                          annotations.
 // Return value:
 //          None.
 DLLEXPORT void STDCALL FPDF_RenderPageBitmap(FPDF_BITMAP bitmap,