init commit

include/mupdf/fitz/display-list.h

@@ -1,3 +1,25 @@
+// Copyright (C) 2004-2021 Artifex Software, Inc.
+//
+// This file is part of MuPDF.
+//
+// MuPDF is free software: you can redistribute it and/or modify it under the
+// terms of the GNU Affero General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option)
+// any later version.
+//
+// MuPDF is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+// FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+// details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with MuPDF. If not, see <https://www.gnu.org/licenses/agpl-3.0.en.html>
+//
+// Alternative licensing terms are available from the licensor.
+// For commercial licensing, see <https://www.artifex.com/> or contact
+// Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco,
+// CA 94129, USA, for further information.
+
 #ifndef MUPDF_FITZ_DISPLAY_LIST_H
 #define MUPDF_FITZ_DISPLAY_LIST_H
 
@@ -6,11 +28,11 @@
 #include "mupdf/fitz/geometry.h"
 #include "mupdf/fitz/device.h"
 
-/*
+/**
 	Display list device -- record and play back device commands.
 */
 
-/*
+/**
 	fz_display_list is a list containing drawing commands (text,
 	images, etc.). The intent is two-fold: as a caching-mechanism
 	to reduce parsing of a page, and to be used as a data
@@ -22,20 +44,21 @@
 	list (once or many times) by calling fz_run_display_list. When
 	the list is no longer needed drop it with fz_drop_display_list.
 */
-typedef struct fz_display_list_s fz_display_list;
+typedef struct fz_display_list fz_display_list;
 
-/*
-	fz_new_display_list: Create an empty display list.
+/**
+	Create an empty display list.
 
 	A display list contains drawing commands (text, images, etc.).
 	Use fz_new_list_device for populating the list.
 
-	mediabox: Bounds of the page (in points) represented by the display list.
+	mediabox: Bounds of the page (in points) represented by the
+	display list.
 */
-fz_display_list *fz_new_display_list(fz_context *ctx, const fz_rect *mediabox);
+fz_display_list *fz_new_display_list(fz_context *ctx, fz_rect mediabox);
 
-/*
-	fz_new_list_device: Create a rendering device for a display list.
+/**
+	Create a rendering device for a display list.
 
 	When the device is rendering a page it will populate the
 	display list with drawing commands (text, images, etc.). The
@@ -44,24 +67,22 @@ fz_display_list *fz_new_display_list(fz_context *ctx, const fz_rect *mediabox);
 	for each rendering. Once the device is no longer needed, free
 	it with fz_drop_device.
 
-	list: A display list that the list device takes ownership of.
+	list: A display list that the list device takes a reference to.
 */
 fz_device *fz_new_list_device(fz_context *ctx, fz_display_list *list);
 
-/*
-	fz_run_display_list: (Re)-run a display list through a device.
+/**
+	(Re)-run a display list through a device.
 
 	list: A display list, created by fz_new_display_list and
 	populated with objects from a page by running fz_run_page on a
 	device obtained from fz_new_list_device.
 
-	dev: Device obtained from fz_new_*_device.
-
 	ctm: Transform to apply to display list contents. May include
 	for example scaling and rotation, see fz_scale, fz_rotate and
 	fz_concat. Set to fz_identity if no transformation is desired.
 
-	area: Only the part of the contents of the display list
+	scissor: Only the part of the contents of the display list
 	visible within this area will be considered when the list is
 	run through the device. This does not imply for tile objects
 	contained in the display list.
@@ -73,25 +94,31 @@ fz_device *fz_new_list_device(fz_context *ctx, fz_display_list *list);
 	progress information back to the caller. The fields inside
 	cookie are continually updated while the page is being run.
 */
-void fz_run_display_list(fz_context *ctx, fz_display_list *list, fz_device *dev, const fz_matrix *ctm, const fz_rect *area, fz_cookie *cookie);
+void fz_run_display_list(fz_context *ctx, fz_display_list *list, fz_device *dev, fz_matrix ctm, fz_rect scissor, fz_cookie *cookie);
 
-/*
-	fz_keep_display_list: Keep a reference to a display list.
+/**
+	Increment the reference count for a display list. Returns the
+	same pointer.
+
+	Never throws exceptions.
 */
 fz_display_list *fz_keep_display_list(fz_context *ctx, fz_display_list *list);
 
-/*
-	fz_drop_display_list: Drop a reference to a display list, freeing it
-	if the reference count reaches zero.
+/**
+	Decrement the reference count for a display list. When the
+	reference count reaches zero, all the references in the display
+	list itself are dropped, and the display list is freed.
+
+	Never throws exceptions.
 */
 void fz_drop_display_list(fz_context *ctx, fz_display_list *list);
 
-/*
-	fz_bound_display_list: Return the bounding box of the page recorded in a display list.
+/**
+	Return the bounding box of the page recorded in a display list.
 */
-fz_rect *fz_bound_display_list(fz_context *ctx, fz_display_list *list, fz_rect *bounds);
+fz_rect fz_bound_display_list(fz_context *ctx, fz_display_list *list);
 
-/*
+/**
 	Create a new image from a display list.
 
 	w, h: The conceptual width/height of the image.
@@ -103,7 +130,7 @@ fz_rect *fz_bound_display_list(fz_context *ctx, fz_display_list *list, fz_rect *
 */
 fz_image *fz_new_image_from_display_list(fz_context *ctx, float w, float h, fz_display_list *list);
 
-/*
+/**
 	Check for a display list being empty
 
 	list: The list to check.