Merge pull request #2776 from wiredfool/docs

Release notes [ci skip]

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. 

docs/reference/internal_design.rst

@@ -6,3 +6,5 @@ Internal Reference Docs
           
   open_files
   limits
+  block_allocator
+             

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.