diff --git a/docs/reference/block_allocator.rst b/docs/reference/block_allocator.rst new file mode 100644 index 000000000..da5b3b8d8 --- /dev/null +++ b/docs/reference/block_allocator.rst @@ -0,0 +1,47 @@ +Block Allocator +=============== + +Previous Design +--------------- + +Historically there have been two image allocators in Pillow: +``ImagingAllocateBlock`` and ``ImagingAllocateArray``. The first works +for images smaller than 16MB of data and allocates one large chunk of +memory of ``im->linesize * im->ysize`` bytes. The second works for +large images and make one allocation for each scan line of size +``im->linesize`` bytes. This makes for a very sharp transition +between one allocation and potentially thousands of small allocations, +leading to unpredictable performance penalties around the transition. + +New Design +---------- + +``ImagingAllocateArray`` now allocates space for images as a chain of +blocks with a maximum size of 16MB. If there is a memory allocation +error, it falls back to allocating a 4KB block, or at least one scan +line. This is now the default for all internal allocations. + +``ImagingAllocateBlock`` is now only used for those cases when we are +specifically requesting a single segment of memory for sharing with +other code. + +Memory Pools +------------ + +There is now a memory pool to contain a supply of recently freed +blocks, which can then be reused without going back to the OS for a +fresh allocation. This caching of free blocks is currently disabled by +default, but can be enabled and tweaked using three environment +variables: + + * ``PILLOW_ALIGNMENT``, in bytes. Specifies the alignment of memory + allocations. Valid values are powers of 2 between 1 and + 128, inclusive. Defaults to 1. + + * ``PILLOW_BLOCK_SIZE``, in bytes, K, or M. Specifies the maximum + block size for ``ImagingAllocateArray``. Valid values are + integers, with an optional `k` or `m` suffix. Defaults to 16M. + + * ``PILLOW_BLOCKS_MAX`` Specifies the number of freed blocks to + retain to fill future memory requests. Any freed blocks over this + threshold will be returned to the OS immediately. Defaults to 0. diff --git a/docs/reference/internal_design.rst b/docs/reference/internal_design.rst index a8d6e2284..4c0fbb85d 100644 --- a/docs/reference/internal_design.rst +++ b/docs/reference/internal_design.rst @@ -6,3 +6,5 @@ Internal Reference Docs open_files limits + block_allocator + diff --git a/docs/releasenotes/4.3.0.rst b/docs/releasenotes/4.3.0.rst index df9aeddc0..649135922 100644 --- a/docs/releasenotes/4.3.0.rst +++ b/docs/releasenotes/4.3.0.rst @@ -87,16 +87,32 @@ operation. The original :py:class:`PIL.ImageFilter.Filter` class remains for image filters that can process only single band images, or require splitting of channels prior to filtering. +Other Changes +============= Loading 16-bit TIFF Images -========================== +^^^^^^^^^^^^^^^^^^^^^^^^^^ Pillow now can read 16-bit multichannel TIFF files including files with alpha transparency. The image data is truncated to 8-bit precision. +Pillow now can read 16-bit signed integer single channel TIFF +files. The image data is promoted to 32-bit for storage and +processing. + +SGI Images +^^^^^^^^^^ + +Pillow can now read and write uncompressed 16-bit multichannel SGI +images to and from RGB and RGBA formats. The image data is truncated +to 8-bit precision. + +Pillow can now read RLE encoded SGI images in both 8 and 16-bit +precision. + Performance -=========== +^^^^^^^^^^^ This release contains several performance improvements: @@ -109,3 +125,14 @@ This release contains several performance improvements: friendly algorithm. * ImageFilters based on Kernel convolution are significantly faster due to the new MultibandFilter feature. +* All memory allocation for images is now done in blocks, rather than + falling back to an allocation for each scan line for images larger + than the block size. + +CMYK Conversion +^^^^^^^^^^^^^^^ + +The basic CMYK->RGB conversion has been tweaked to match the formula +from Google Chrome. This produces an image that is generally lighter +than the previous formula, and more in line with what color managed +applications produce.