From 05d754964452918a23041742582ee509be351dd8 Mon Sep 17 00:00:00 2001 From: geisserml Date: Sat, 17 Sep 2022 14:29:31 +0200 Subject: [PATCH] docs: better integrate new allocator parameter --- docs/devel/changelog_staging.md | 2 +- src/pypdfium2/_helpers/page.py | 24 ++++++++++++++++-------- 2 files changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/devel/changelog_staging.md b/docs/devel/changelog_staging.md index d7a45c498..ad5224dd3 100644 --- a/docs/devel/changelog_staging.md +++ b/docs/devel/changelog_staging.md @@ -20,7 +20,7 @@ *Other changes* - Improved code style and consistency regarding interaction with PDFium/ctypes. - - New rendering parameters added: `color_scheme`, `fill_to_stroke`, `force_halftone`, `draw_forms`, `rev_byteorder`, `extra_flags`, and `memory_limit`. + - New rendering parameters added: `color_scheme`, `fill_to_stroke`, `force_halftone`, `draw_forms`, `rev_byteorder`, `extra_flags`, `allocator`, and `memory_limit`. - New rendering functions `render_tonumpy()` added, returning a shaped NumPy array. - New method `PdfDocument.get_page_size()` to retrieve page size by index without needing to load a `PdfPage` (uses `FPDF_GetPageSizeByIndexF()` under the hood). - All document-level methods that take a page index now accept negative values for reverse indexing. diff --git a/src/pypdfium2/_helpers/page.py b/src/pypdfium2/_helpers/page.py index f2c5a2c4f..18479a5f4 100644 --- a/src/pypdfium2/_helpers/page.py +++ b/src/pypdfium2/_helpers/page.py @@ -295,7 +295,7 @@ def render_base( memory_limit = 2**30, ): """ - Rasterise the page to a ctypes ubyte array. + Rasterise the page to a :class:`ctypes.c_ubyte` array. This is the base method for :meth:`.render_tobytes`, :meth:`.render_tonumpy` and :meth:`.render_topil`. Parameters: @@ -357,25 +357,33 @@ def render_base( Additional PDFium rendering flags. Multiple flags may be combined with binary OR. Flags not covered by other options include :data:`FPDF_RENDER_LIMITEDIMAGECACHE` and :data:`FPDF_NO_NATIVETEXT`, for instance. - allocator (typing.Callable): - A custom function to provide a ctypes.c_ubyte array. It is called with the required number of bytes (i. e. the length the array shall have). - This may be used to directly write the pixel data to a specific place in memory (e. g. a GUI widget buffer), avoiding unnecessary data copying. + allocator (typing.Callable | None): + + | A function to provide a custom :class:`ctypes.c_ubyte` array. It is called with the required number of bytes (i. e. the length the array shall have). + | If not given, a new buffer is allocated by ctypes (not PDFium), so Python takes care of all memory management. + + | If you wish to render to an existing buffer that was not alloacted by ctypes itself, note that you may get a ctypes array representation of arbitrary memory using ``(ctypes.c_ubyte*n_bytes).from_address(mem_address)``, where *n_bytes* shall be the number of bytes to encompass, and *mem_address* the memory address of the first byte. + | This may be used to directly write the pixel data to a specific place in memory (e. g. a GUI widget buffer), avoiding unnecessary data copying. + + Callers must ensure that ... + + * the buffer and its ctypes representation are large enough to hold the requested number of bytes + * the memory remains valid as long as the ctypes array is used + * the memory is freed once it is not needed anymore memory_limit (int | None): Maximum number of bytes that may be allocated (defaults to 1 GiB rsp. 2^30 bytes). - If the limit is exceeded, a :exc:`RuntimeError` will be raised. + If the limit would be exceeded, a :exc:`RuntimeError` is raised. If :data:`None` or 0, this function may allocate arbitrary amounts of memory as far as Python and the OS permit. Returns: (ctypes.c_ubyte array, str, (int, int)): Ctypes array, color format, and image size. - The color format may be ``BGR/RGB``, ``BGRA/RGBA``, or ``L``, depending on the parameters *color*, *greyscale* and *rev_byteorder*. + The color format may be ``BGR``/``RGB``, ``BGRA``/``RGBA``, or ``L``, depending on the parameters *color*, *greyscale* and *rev_byteorder*. Image size is given in pixels as a tuple of width and height. Hint: To convert a DPI value to a scale factor, divide it by 72. - Note: - The ctypes array is allocated by Python (not PDFium), so we don't need to care about freeing memory. """ validate_colors(color, color_scheme)