+ added a new parameter int[] dstArray in the methods getByteArray, getInt32Array of classes HeicImage and HeicImageFrame. It allows allocating the destination buffer only once.

Evgeniy Sidenko · Evgeniy Sidenko · commit aca1ab68769e · 2025-06-11T21:47:24.000-04:00
* updated API documentation
diff --git a/README.md b/README.md
@@ -44,12 +44,21 @@ try (IOFileStream fs = new IOFileStream("filename.heic", IOMode.READ))
 {
     HeicImage image = HeicImage.load(fs);
      
-    int[] pixels = frames.get(key).getInt32Array(PixelFormat.Argb32);
     var width = (int)image.Width;
-    var height = (int)image.Height;
-	
+    var height = (int)image.Height;	
 	BufferedImage image2 = new BufferedImage(width, height, BufferedImage.TYPE_INT_ARGB);
-	image2.setRGB(0, 0, width, height, pixels, 0, width);
+
+	final int[] dstArray = ((DataBufferInt) image2.getRaster()
+                                                  .getDataBuffer()).getData();
+
+    int[] pixels = frames.get(key).getInt32Array(PixelFormat.Argb32, dstArray);
+
+	
+	if (pixels != dstArray)
+	{
+		image2.setRGB(0, 0, width, height, pixels, 0, width);
+	}
+	
 	ImageIO.write(image2, "JPEG", new File("output.jpg"));
 }
 ```
@@ -60,12 +69,21 @@ try (IOFileStream fs = new IOFileStream("filename.heic", IOMode.READ))
 {
     HeicImage image = HeicImage.load(fs);
      
-    int[] pixels = frames.get(key).getInt32Array(PixelFormat.Argb32);
     var width = (int)image.Width;
     var height = (int)image.Height;
 	
-	BufferedImage image2 = new BufferedImage(width, height, BufferedImage.TYPE_INT_ARGB);
-	image2.setRGB(0, 0, width, height, pixels, 0, width);
+	BufferedImage image2 = new BufferedImage(width, height, BufferedImage.TYPE_INT_ARGB);
+
+	final int[] dstArray = ((DataBufferInt) image2.getRaster()
+                                                  .getDataBuffer()).getData();
+
+    int[] pixels = frames.get(key).getInt32Array(PixelFormat.Argb32, dstArray);
+
+	if (pixels != dstArray)
+	{
+		image2.setRGB(0, 0, width, height, pixels, 0, width);
+	}
+		
 	ImageIO.write(image2, "PNG", new File("output.png"));
 }
 ```
@@ -76,13 +94,18 @@ try (IOFileStream fs = new IOFileStream("filename.heic", IOMode.READ))
 {
     HeicImage image = HeicImage.load(fs);
 
-    int[] pixels = image.getInt32Array(PixelFormat.Argb32);
     int width = (int)image.getWidth();
     int height = (int)image.getHeight();
-    int i = 0;
 
 	BufferedImage outImage = new BufferedImage(width, height, BufferedImage.TYPE_INT_ARGB);
-	outImage.setRGB(0, 0, width, height, pixels, 0, width);
+	final int[] dstArray = ((DataBufferInt) outImage.getRaster()
+                                                  .getDataBuffer()).getData();
+	int[] pixels = image.getInt32Array(PixelFormat.Argb32, dstArray);
+
+	if (pixels != dstArray)
+	{
+		outImage.setRGB(0, 0, width, height, pixels, 0, width);
+	}
 	ImageIO.write(outImage, "PNG", new File("output.png"));
 }
 ```
@@ -98,10 +121,18 @@ try (IOFileStream fs = new IOFileStream("filename.heic", IOMode.READ))
 	{
 		int width = (int)frames.get(key).getWidth();
 		int height = (int)frames.get(key).getHeight();
-		int[] pixels = frames.get(key).getInt32Array(PixelFormat.Argb32);
-
+		
 		BufferedImage image2 = new BufferedImage(width, height, BufferedImage.TYPE_INT_ARGB);
-		image2.setRGB(0, 0, width, height, pixels, 0, width);
+		final int[] dstArray = ((DataBufferInt) image2.getRaster()
+                                                  .getDataBuffer()).getData();
+												  
+		int[] pixels = frames.get(key).getInt32Array(PixelFormat.Argb32, dstArray);
+		
+		if (pixels != dstArray)
+		{
+			image2.setRGB(0, 0, width, height, pixels, 0, width);
+		}
+		
 		ImageIO.write(image2, "PNG", new File("output"+key+".png"));
 	}
 }
@@ -110,8 +141,8 @@ try (IOFileStream fs = new IOFileStream("filename.heic", IOMode.READ))
 ## Documentation
 
 All public classes, methods and properties are documented in corresponding API_README:
-* [/Openize.Heic.Decoder/docs/API_README.md](https://github.com/openize-com/openize-heic-java/blob/main/docs/Openize.Heic.Decoder/API_README.md) for Openize.Heic.Decoder;
-* [/Openize.IsoBmff/docs/API_README.md](https://github.com/openize-com/openize-heic-java/blob/main/docs/Openize.IsoBmff/API_README.md) for Openize.IsoBmff.
+* [/Openize.Heic.Decoder/docs/API_README.md](/docs/Openize.Heic.Decoder/API_README.md) for Openize.Heic.Decoder;
+* [/Openize.IsoBmff/docs/API_README.md](/docs/Openize.IsoBmff/API_README.md) for Openize.IsoBmff.
 
 ### HeicImage
 
@@ -120,8 +151,8 @@ Name | Type | Description | Parameters | Notes
 ------------ | ------------- | ------------- | ------------- | -------------
 **load** | **HeicImage** | Reads the file meta data and creates a class object for further decoding of the file contents. | `Stream stream` - File stream. | This operation does not decode pixels. Use the default frame methods GetByteArray or GetInt32Array afterwards in order to decode pixels.
 **canLoad** | **boolean** | Checks if the stream can be read as a heic image. Returns true if file header contains heic signarure, false otherwise | `Stream stream` - File stream. | 
-**getByteArray** | **byte[]** | Get pixel data of the default image frame in the format of byte array.<br />Each three or four bytes (the count depends on the pixel format) refer to one pixel left to right top to bottom line by line.<br />Returns null if frame does not contain image data. | `PixelFormat pixelFormat` - Pixel format that defines the order of colors and the presence of alpha byte.<br />`Rectangle boundsRectangle` - Bounds of the requested area.
-**getInt32Array** | **int[]** | Get pixel data of the default image frame in the format of integer array.<br />Each int value refers to one pixel left to right top to bottom line by line.<br />Returns null if frame does not contain image data. | `PixelFormat pixelFormat` - Pixel format that defines the order of colors.<br />`Rectangle boundsRectangle` - Bounds of the requested area.
+**getByteArray** | **byte[]** | Get pixel data of the default image frame in the format of byte array.<br />Each three or four bytes (the count depends on the pixel format) refer to one pixel left to right top to bottom line by line.<br />Returns null if frame does not contain image data. In general, it equals to `dstArray`. | `PixelFormat pixelFormat` - Pixel format that defines the order of colors and the presence of alpha byte.<br />`Rectangle boundsRectangle` - Bounds of the requested area.<br/>`byte[] dstArray` - Byte array for storing the pixel values. If it is `null` or its length is less than necessary the new array will be allocated and returned.
+**getInt32Array** | **int[]** | Get pixel data of the default image frame in the format of integer array.<br />Each int value refers to one pixel left to right top to bottom line by line.<br />Returns null if frame does not contain image data. In general, it equals to `dstArray`. | `PixelFormat pixelFormat` - Pixel format that defines the order of colors.<br />`Rectangle boundsRectangle` - Bounds of the requested area.<br/>`int[] dstArray` - Integer array for storing the argb values. If it is `null` or its length is less than necessary the new array will be allocated and returned.
 
 
 #### Properties
@@ -136,8 +167,8 @@ Name | Type | Description
 #### Methods
 Name | Type | Description | Parameters
 ------------ | ------------- | ------------- | -------------
-**getByteArray** | **byte[]** | Get pixel data in the format of byte array. Each three or four bytes (the count depends on the pixel format) refer to one pixel left to right top to bottom line by line. | `PixelFormat pixelFormat` - Pixel format that defines the order of colors and the presence of alpha byte. `Rectangle boundsRectangle` - Bounds of the requested area.
-**getInt32Array** | **int[]** | Get pixel data in the format of integer array. Each int value refers to one pixel left to right top to bottom line by line. | `PixelFormat pixelFormat` - Pixel format that defines the order of colors. `Rectangle boundsRectangle` - Bounds of the requested area.
+**getByteArray** | **byte[]** | Get pixel data in the format of byte array. Each three or four bytes (the count depends on the pixel format) refer to one pixel left to right top to bottom line by line. In general, it equals to `dstArray`. | `PixelFormat pixelFormat` - Pixel format that defines the order of colors and the presence of alpha byte. `Rectangle boundsRectangle` - Bounds of the requested area.<br/>`byte[] dstArray` - Byte array for storing the pixel values. If it is `null` or its length is less than necessary the new array will be allocated and returned.
+**getInt32Array** | **int[]** | Get pixel data in the format of integer array. Each int value refers to one pixel left to right top to bottom line by line. In general, it equals to `dstArray`. | `PixelFormat pixelFormat` - Pixel format that defines the order of colors. `Rectangle boundsRectangle` - Bounds of the requested area.<br/>`int[] dstArray` - Integer array for storing the argb values. If it is `null` or its length is less than necessary the new array will be allocated and returned.
 **getTextData** | **String** | Get frame text data. Exists only for mime frame types. | 
 
 ### Properties
diff --git a/docs/Openize.Heic.Decoder/HeicImage.md b/docs/Openize.Heic.Decoder/HeicImage.md
@@ -17,9 +17,9 @@ Name | Type | Description | Notes
 
 Name | Type | Description | Parameters | Notes
 ------------ | ------------- | ------------- | ------------- | -------------
-**load** | **HeicImage** | Reads the file meta data and creates a class object for further decoding of the file contents. | Stream **stream** - File stream. | This operation does not decode pixels.<br />Use the default frame methods GetByteArray or GetInt32Array afterwards in order to decode pixels.
-**canLoad** | **boolean** | Checks if the stream can be read as a heic image.<br />Returns true if file header contains heic signarure, false otherwise | Stream **stream** - File stream. | 
-**getByteArray** | **byte[]** | Get pixel data of the default image frame in the format of byte array.<br />Each three or four bytes (the count depends on the pixel format) refer to one pixel left to right top to bottom line by line.<br />Returns null if frame does not contain image data. | PixelFormat <b>pixelFormat</b> - Pixel format that defines the order of colors and the presence of alpha byte.<br />Rectangle <b>boundsRectangle</b> - Bounds of the requested area.
-**getInt32Array** | **int[]** | Get pixel data of the default image frame in the format of integer array.<br />Each int value refers to one pixel left to right top to bottom line by line.<br />Returns null if frame does not contain image data. | PixelFormat <b>pixelFormat</b> - Pixel format that defines the order of colors.<br />Rectangle <b>boundsRectangle</b> - Bounds of the requested area.
+**load** | **HeicImage** | Reads the file meta data and creates a class object for further decoding of the file contents. | **IOStream** ***stream*** - File stream. | This operation does not decode pixels.<br />Use the default frame methods GetByteArray or GetInt32Array afterwards in order to decode pixels.
+**canLoad** | **boolean** | Checks if the stream can be read as a heic image.<br />Returns true if file header contains heic signarure, false otherwise | **IOStream** ***stream*** - File stream. | 
+**getByteArray** | **byte[]** | Get pixel data of the default image frame in the format of byte array.<br />Each three or four bytes (the count depends on the pixel format) refer to one pixel left to right top to bottom line by line.<br/>Returns null if frame does not contain image data. In general, it equals to ***dstArray***. | **PixelFormat**<br/> ***pixelFormat*** - Pixel format that defines the order of colors and the presence of alpha byte.<br/>**Rectangle**<br/>***boundsRectangle*** - Bounds of the requested area.<br/>**byte[]**<br/>***dstArray*** - Byte array for storing the pixel values. If it is `null` or its length is less than necessary the new array will be allocated and returned.
+**getInt32Array** | **int[]** | Get pixel data of the default image frame in the format of integer array.<br />Each int value refers to one pixel left to right top to bottom line by line.<br />Returns **null** if frame does not contain image data. In general, it equals to ***dstArray***. | **PixelFormat**<br/>***pixelFormat*** - Pixel format that defines the order of colors.<br />**Rectangle**<br/>***boundsRectangle*** - Bounds of the requested area.<br/>**int[]**<br/>***dstArray*** - Integer array for storing the argb values. If it is `null` or its length is less than necessary the new array will be allocated and returned.
 
 [[Back to API_README]](API_README.md)
diff --git a/docs/Openize.Heic.Decoder/HeicImageFrame.md b/docs/Openize.Heic.Decoder/HeicImageFrame.md
@@ -23,8 +23,8 @@ Name | Type | Description | Notes
 
 Name | Type | Description | Parameters
 ------------ | ------------- | ------------- | -------------
-**getByteArray** | **byte[]** | Get pixel data in the format of byte array.<br />Each three or four bytes (the count depends on the pixel format) refer to one pixel left to right top to bottom line by line.<br />Returns null if frame does not contain image data. | PixelFormat **pixelFormat** - Pixel format that defines the order of colors and the presence of alpha byte.<br />Rectangle **boundsRectangle** - Bounds of the requested area.
-**getInt32Array** | **int[]** | Get pixel data in the format of integer array.<br />Each int value refers to one pixel left to right top to bottom line by line.<br />Returns null if frame does not contain image data. | PixelFormat **pixelFormat** - Pixel format that defines the order of colors.<br />Rectangle **boundsRectangle** - Bounds of the requested area.
+**getByteArray** | **byte[]** | Get pixel data in the format of byte array.<br />Each three or four bytes (the count depends on the pixel format) refer to one pixel left to right top to bottom line by line.<br />Returns null if frame does not contain image data. In general, it equals to ***dstArray***. | **PixelFormat **<br/>***pixelFormat*** - Pixel format that defines the order of colors and the presence of alpha byte.<br />**Rectangle**<br/>***boundsRectangle*** - Bounds of the requested area.<br/>**byte[]**<br/>***dstArray*** - Byte array for storing the pixel values. If it is `null` or its length is less than necessary the new array will be allocated and returned.
+**getInt32Array** | **int[]** | Get pixel data in the format of integer array.<br />Each int value refers to one pixel left to right top to bottom line by line.<br />Returns null if frame does not contain image data. In general, it equals to ***dstArray***. | **PixelFormat**<br/>***pixelFormat*** - Pixel format that defines the order of colors.<br />**Rectangle**<br/>***boundsRectangle*** - Bounds of the requested area.<br/>**int[]**<br/>***dstArray*** - Integer array for storing the argb values. If it is `null` or its length is less than necessary the new array will be allocated and returned.
 **getTextData** | **String** | Get frame text data.<br />Exists only for mime frame types. | 
 
 ## Fields
diff --git a/pom.xml b/pom.xml
@@ -6,7 +6,7 @@
 
     <groupId>openize</groupId>
     <artifactId>openize-heic</artifactId>
-    <version>25.4</version>
+    <version>25.6</version>
 	<name>Openize.HEIC for Java</name>
 	<description>Openize.Heic is an open source implementation of the ISO/IEC 23008-12:2017 HEIF file format decoder. It is written from scratch and has a plain Java API to enable a simple integration into other software.</description>
 	<url>https://github.com/openize-heic/Openize.HEIC-for-Java</url>
diff --git a/src/main/java/openize/heic/decoder/HeicImage.java b/src/main/java/openize/heic/decoder/HeicImage.java
@@ -132,7 +132,23 @@ public static boolean canLoad(IOStream stream)
      */
     public final /*Byte*/byte[] getByteArray(PixelFormat pixelFormat)
     {
-        return getByteArray(pixelFormat, new Rectangle());
+        return getByteArray(pixelFormat, new Rectangle(), null);
+    }
+
+    /**
+     * <p>
+     * Get pixel data of the default image frame in the format of byte array.
+     * </p>
+     * <p>Each three or four bytes (the count depends on the pixel format) refer to one pixel left to right top to bottom line by line.</p>
+     *
+     * @param pixelFormat     Pixel format that defines the order of colors and the presence of alpha byte.
+     * @param dstArray        Byte array for storing the pixel values. If {@code null} or its length is less than
+     *                        necessary the new array will be allocated and returned.
+     * @return Byte array, null if frame does not contain image data. In general, it equals to {@code dstArray}.
+     */
+    public final /*Byte*/byte[] getByteArray(PixelFormat pixelFormat, byte[] dstArray)
+    {
+        return getDefaultFrame().getByteArray(pixelFormat, new Rectangle(), dstArray);
     }
 
     /**
@@ -143,11 +159,13 @@ public static boolean canLoad(IOStream stream)
      *
      * @param pixelFormat     Pixel format that defines the order of colors and the presence of alpha byte.
      * @param boundsRectangle Bounds of the requested area.
-     * @return Byte array, null if frame does not contain image data.
+     * @param dstArray        Byte array for storing the pixel values. If {@code null} or its length is less than
+     *                        necessary the new array will be allocated and returned.
+     * @return Byte array, null if frame does not contain image data. In general, it equals to {@code dstArray}.
      */
-    public final /*Byte*/byte[] getByteArray(PixelFormat pixelFormat, Rectangle boundsRectangle)
+    public final /*Byte*/byte[] getByteArray(PixelFormat pixelFormat, Rectangle boundsRectangle, byte[] dstArray)
     {
-        return getDefaultFrame().getByteArray(pixelFormat, boundsRectangle);
+        return getDefaultFrame().getByteArray(pixelFormat, boundsRectangle, dstArray);
     }
 
     /**
@@ -161,7 +179,23 @@ public static boolean canLoad(IOStream stream)
      */
     public final int[] getInt32Array(PixelFormat pixelFormat)
     {
-        return getInt32Array(pixelFormat, new Rectangle());
+        return getInt32Array(pixelFormat, new Rectangle(), null);
+    }
+
+    /**
+     * <p>
+     * Get pixel data of the default image frame in the format of integer array.
+     * </p>
+     * <p>Each int value refers to one pixel left to right top to bottom line by line.</p>
+     *
+     * @param pixelFormat     Pixel format that defines the order of colors.
+     * @param dstArray        Integer array for storing the argb values. If {@code null} or its length is less than
+     *                        necessary the new array will be allocated and returned.
+     * @return Integer array, null if frame does not contain image data. In general, it equals to {@code dstArray}.
+     */
+    public final int[] getInt32Array(PixelFormat pixelFormat, int[] dstArray)
+    {
+        return getInt32Array(pixelFormat, new Rectangle(), dstArray);
     }
 
     /**
@@ -172,11 +206,13 @@ public final int[] getInt32Array(PixelFormat pixelFormat)
      *
      * @param pixelFormat     Pixel format that defines the order of colors.
      * @param boundsRectangle Bounds of the requested area.
-     * @return Integer array, null if frame does not contain image data.
+     * @param dstArray        Integer array for storing the argb values. If {@code null} or its length is less than
+     *                        necessary the new array will be allocated and returned.
+     * @return Integer array, null if frame does not contain image data. In general, it equals to {@code dstArray}.
      */
-    public final int[] getInt32Array(PixelFormat pixelFormat, Rectangle boundsRectangle)
+    public final int[] getInt32Array(PixelFormat pixelFormat, Rectangle boundsRectangle, int[] dstArray)
     {
-        return getDefaultFrame().getInt32Array(pixelFormat, boundsRectangle);
+        return getDefaultFrame().getInt32Array(pixelFormat, boundsRectangle, dstArray);
     }
 
     /**
diff --git a/src/main/java/openize/heic/decoder/HeicImageFrame.java b/src/main/java/openize/heic/decoder/HeicImageFrame.java
