Debian Codegraph @

java/org/libjpegturbo/turbojpeg/YUVImage.java

raw
1 /*
2 * Copyright (C)2014, 2017, 2023-2024 D. R. Commander. All Rights Reserved.
3 * Copyright (C)2015 Viktor Szathmáry. All Rights Reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 *
8 * - Redistributions of source code must retain the above copyright notice,
9 * this list of conditions and the following disclaimer.
10 * - Redistributions in binary form must reproduce the above copyright notice,
11 * this list of conditions and the following disclaimer in the documentation
12 * and/or other materials provided with the distribution.
13 * - Neither the name of the libjpeg-turbo Project nor the names of its
14 * contributors may be used to endorse or promote products derived from this
15 * software without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS",
18 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
21 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27 * POSSIBILITY OF SUCH DAMAGE.
28 */
29
30 package org.libjpegturbo.turbojpeg;
31
32 /**
33 * This class encapsulates a planar YUV image and the metadata
34 * associated with it. The TurboJPEG API allows both the JPEG compression and
35 * decompression pipelines to be split into stages: YUV encode, compress from
36 * YUV, decompress to YUV, and YUV decode. A <code>YUVImage</code> instance
37 * serves as the destination image for YUV encode and decompress-to-YUV
38 * operations and as the source image for compress-from-YUV and YUV decode
39 * operations.
40 *
41 * <p>Technically, the JPEG format uses the YCbCr colorspace (which is
42 * technically not a colorspace but a color transform), but per the convention
43 * of the digital video community, the TurboJPEG API uses "YUV" to refer to an
44 * image format consisting of Y, Cb, and Cr image planes.
45 *
46 * <p>Each plane is simply a 2D array of bytes, each byte representing the
47 * value of one of the components (Y, Cb, or Cr) at a particular location in
48 * the image. The width and height of each plane are determined by the image
49 * width, height, and level of chrominance subsampling. The luminance plane
50 * width is the image width padded to the nearest multiple of the horizontal
51 * subsampling factor (1 in the case of 4:4:4, grayscale, 4:4:0, or 4:4:1; 2 in
52 * the case of 4:2:2 or 4:2:0; 4 in the case of 4:1:1.) Similarly, the
53 * luminance plane height is the image height padded to the nearest multiple of
54 * the vertical subsampling factor (1 in the case of 4:4:4, 4:2:2, grayscale,
55 * or 4:1:1; 2 in the case of 4:2:0 or 4:4:0; 4 in the case of 4:4:1.) This is
56 * irrespective of any additional padding that may be specified as an argument
57 * to the various YUVImage methods. The chrominance plane width is equal to
58 * the luminance plane width divided by the horizontal subsampling factor, and
59 * the chrominance plane height is equal to the luminance plane height divided
60 * by the vertical subsampling factor.
61 *
62 * <p>For example, if the source image is 35 x 35 pixels and 4:2:2 subsampling
63 * is used, then the luminance plane would be 36 x 35 bytes, and each of the
64 * chrominance planes would be 18 x 35 bytes. If you specify a row alignment
65 * of 4 bytes on top of this, then the luminance plane would be 36 x 35 bytes,
66 * and each of the chrominance planes would be 20 x 35 bytes.
67 */
68 public class YUVImage {
69
70 private static final String NO_ASSOC_ERROR =
71 "No image data is associated with this instance";
72
73 /**
74 * Create a new <code>YUVImage</code> instance backed by separate image
75 * planes, and allocate memory for the image planes.
76 *
77 * @param width width (in pixels) of the YUV image
78 *
79 * @param strides an array of integers, each specifying the number of bytes
80 * per row in the corresponding plane of the YUV image. Setting the stride
81 * for any plane to 0 is the same as setting it to the plane width (see
82 * {@link YUVImage above}.) If <code>strides</code> is null, then the
83 * strides for all planes will be set to their respective plane widths. When
84 * using this constructor, the stride for each plane must be equal to or
85 * greater than the plane width.
86 *
87 * @param height height (in pixels) of the YUV image
88 *
89 * @param subsamp the level of chrominance subsampling to be used in the YUV
90 * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
91 */
92 public YUVImage(int width, int[] strides, int height, int subsamp) {
93 setBuf(null, null, width, strides, height, subsamp, true);
94 }
95
96 /**
97 * Create a new <code>YUVImage</code> instance backed by a unified buffer,
98 * and allocate memory for the buffer.
99 *
100 * @param width width (in pixels) of the YUV image
101 *
102 * @param align row alignment (in bytes) of the YUV image (must be a power of
103 * 2.) Setting this parameter to n specifies that each row in each plane of
104 * the YUV image will be padded to the nearest multiple of n bytes
105 * (1 = unpadded.)
106 *
107 * @param height height (in pixels) of the YUV image
108 *
109 * @param subsamp the level of chrominance subsampling to be used in the YUV
110 * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
111 */
112 public YUVImage(int width, int align, int height, int subsamp) {
113 setBuf(new byte[TJ.bufSizeYUV(width, align, height, subsamp)], width,
114 align, height, subsamp);
115 }
116
117 /**
118 * Create a new <code>YUVImage</code> instance from a set of existing image
119 * planes.
120 *
121 * @param planes an array of buffers representing the Y, U (Cb), and V (Cr)
122 * image planes (or just the Y plane, if the image is grayscale.) These
123 * planes can be contiguous or non-contiguous in memory. Plane
124 * <code>i</code> should be at least <code>offsets[i] +
125 * {@link TJ#planeSizeYUV TJ.planeSizeYUV}(i, width, strides[i], height, subsamp)</code>
126 * bytes in size.
127 *
128 * @param offsets If this <code>YUVImage</code> instance represents a
129 * subregion of a larger image, then <code>offsets[i]</code> specifies the
130 * offset (in bytes) of the subregion within plane <code>i</code> of the
131 * larger image. Setting this to null is the same as setting the offsets for
132 * all planes to 0.
133 *
134 * @param width width (in pixels) of the new YUV image (or subregion)
135 *
136 * @param strides an array of integers, each specifying the number of bytes
137 * per row in the corresponding plane of the YUV image. Setting the stride
138 * for any plane to 0 is the same as setting it to the plane width (see
139 * {@link YUVImage above}.) If <code>strides</code> is null, then the
140 * strides for all planes will be set to their respective plane widths. You
141 * can adjust the strides in order to add an arbitrary amount of row padding
142 * to each plane or to specify that this <code>YUVImage</code> instance is a
143 * subregion of a larger image (in which case, <code>strides[i]</code> should
144 * be set to the plane width of plane <code>i</code> in the larger image.)
145 *
146 * @param height height (in pixels) of the new YUV image (or subregion)
147 *
148 * @param subsamp the level of chrominance subsampling used in the YUV
149 * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
150 */
151 public YUVImage(byte[][] planes, int[] offsets, int width, int[] strides,
152 int height, int subsamp) {
153 setBuf(planes, offsets, width, strides, height, subsamp, false);
154 }
155
156 /**
157 * Create a new <code>YUVImage</code> instance from an existing unified
158 * buffer.
159 *
160 * @param yuvImage buffer that contains or will receive a unified planar YUV
161 * image. Use {@link TJ#bufSizeYUV TJ.bufSizeYUV()} to determine the minimum
162 * size for this buffer. The Y, U (Cb), and V (Cr) image planes are stored
163 * sequentially in the buffer. (See {@link YUVImage above} for a description
164 * of the image format.)
165 *
166 * @param width width (in pixels) of the YUV image
167 *
168 * @param align row alignment (in bytes) of the YUV image (must be a power of
169 * 2.) Setting this parameter to n specifies that each row in each plane of
170 * the YUV image will be padded to the nearest multiple of n bytes
171 * (1 = unpadded.)
172 *
173 * @param height height (in pixels) of the YUV image
174 *
175 * @param subsamp the level of chrominance subsampling used in the YUV
176 * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
177 */
178 public YUVImage(byte[] yuvImage, int width, int align, int height,
179 int subsamp) {
180 setBuf(yuvImage, width, align, height, subsamp);
181 }
182
183 /**
184 * Assign a set of image planes to this <code>YUVImage</code> instance.
185 *
186 * @param planes an array of buffers representing the Y, U (Cb), and V (Cr)
187 * image planes (or just the Y plane, if the image is grayscale.) These
188 * planes can be contiguous or non-contiguous in memory. Plane
189 * <code>i</code> should be at least <code>offsets[i] +
190 * {@link TJ#planeSizeYUV TJ.planeSizeYUV}(i, width, strides[i], height, subsamp)</code>
191 * bytes in size.
192 *
193 * @param offsets If this <code>YUVImage</code> instance represents a
194 * subregion of a larger image, then <code>offsets[i]</code> specifies the
195 * offset (in bytes) of the subregion within plane <code>i</code> of the
196 * larger image. Setting this to null is the same as setting the offsets for
197 * all planes to 0.
198 *
199 * @param width width (in pixels) of the YUV image (or subregion)
200 *
201 * @param strides an array of integers, each specifying the number of bytes
202 * per row in the corresponding plane of the YUV image. Setting the stride
203 * for any plane to 0 is the same as setting it to the plane width (see
204 * {@link YUVImage above}.) If <code>strides</code> is null, then the
205 * strides for all planes will be set to their respective plane widths. You
206 * can adjust the strides in order to add an arbitrary amount of row padding
207 * to each plane or to specify that this <code>YUVImage</code> instance is a
208 * subregion of a larger image (in which case, <code>strides[i]</code> should
209 * be set to the plane width of plane <code>i</code> in the larger image.)
210 *
211 * @param height height (in pixels) of the YUV image (or subregion)
212 *
213 * @param subsamp the level of chrominance subsampling used in the YUV
214 * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
215 */
216 public void setBuf(byte[][] planes, int[] offsets, int width, int[] strides,
217 int height, int subsamp) {
218 setBuf(planes, offsets, width, strides, height, subsamp, false);
219 }
220
221 private void setBuf(byte[][] planes, int[] offsets, int width, int[] strides,
222 int height, int subsamp, boolean alloc) {
223 if ((planes == null && !alloc) || width < 1 || height < 1 || subsamp < 0 ||
224 subsamp >= TJ.NUMSAMP)
225 throw new IllegalArgumentException("Invalid argument in YUVImage.setBuf()");
226
227 int nc = (subsamp == TJ.SAMP_GRAY ? 1 : 3);
228 if ((planes != null && planes.length != nc) ||
229 (offsets != null && offsets.length != nc) ||
230 (strides != null && strides.length != nc))
231 throw new IllegalArgumentException("YUVImage.setBuf(): planes, offsets, or strides array is the wrong size");
232
233 if (planes == null)
234 planes = new byte[nc][];
235 if (offsets == null)
236 offsets = new int[nc];
237 if (strides == null)
238 strides = new int[nc];
239
240 for (int i = 0; i < nc; i++) {
241 int pw = TJ.planeWidth(i, width, subsamp);
242 int ph = TJ.planeHeight(i, height, subsamp);
243 int planeSize = TJ.planeSizeYUV(i, width, strides[i], height, subsamp);
244
245 if (strides[i] == 0)
246 strides[i] = pw;
247 if (alloc) {
248 if (strides[i] < pw)
249 throw new IllegalArgumentException("Stride must be >= plane width when allocating a new YUV image");
250 planes[i] = new byte[strides[i] * ph];
251 }
252 if (planes[i] == null || offsets[i] < 0)
253 throw new IllegalArgumentException("Invalid argument in YUVImage.setBuf()");
254 if (strides[i] < 0 && offsets[i] - planeSize + pw < 0)
255 throw new IllegalArgumentException("Stride for plane " + i +
256 " would cause memory to be accessed below plane boundary");
257 if (planes[i].length < offsets[i] + planeSize)
258 throw new IllegalArgumentException("Image plane " + i +
259 " is not large enough");
260 }
261
262 yuvPlanes = planes;
263 yuvOffsets = offsets;
264 yuvWidth = width;
265 yuvStrides = strides;
266 yuvHeight = height;
267 yuvSubsamp = subsamp;
268 }
269
270 /**
271 * Assign a unified buffer to this <code>YUVImage</code> instance.
272 *
273 * @param yuvImage buffer that contains or will receive a unified planar YUV
274 * image. Use {@link TJ#bufSizeYUV TJ.bufSizeYUV()} to determine the minimum
275 * size for this buffer. The Y, U (Cb), and V (Cr) image planes are stored
276 * sequentially in the buffer. (See {@link YUVImage above} for a description
277 * of the image format.)
278 *
279 * @param width width (in pixels) of the YUV image
280 *
281 * @param align row alignment (in bytes) of the YUV image (must be a power of
282 * 2.) Setting this parameter to n specifies that each row in each plane of
283 * the YUV image will be padded to the nearest multiple of n bytes
284 * (1 = unpadded.)
285 *
286 * @param height height (in pixels) of the YUV image
287 *
288 * @param subsamp the level of chrominance subsampling used in the YUV
289 * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
290 */
291 public void setBuf(byte[] yuvImage, int width, int align, int height,
292 int subsamp) {
293 if (yuvImage == null || width < 1 || align < 1 ||
294 ((align & (align - 1)) != 0) || height < 1 || subsamp < 0 ||
295 subsamp >= TJ.NUMSAMP)
296 throw new IllegalArgumentException("Invalid argument in YUVImage.setBuf()");
297 if (yuvImage.length < TJ.bufSizeYUV(width, align, height, subsamp))
298 throw new IllegalArgumentException("YUV buffer is not large enough");
299
300 int nc = (subsamp == TJ.SAMP_GRAY ? 1 : 3);
301 byte[][] planes = new byte[nc][];
302 int[] strides = new int[nc];
303 int[] offsets = new int[nc];
304
305 planes[0] = yuvImage;
306 strides[0] = pad(TJ.planeWidth(0, width, subsamp), align);
307 if (subsamp != TJ.SAMP_GRAY) {
308 strides[1] = strides[2] = pad(TJ.planeWidth(1, width, subsamp), align);
309 planes[1] = planes[2] = yuvImage;
310 offsets[1] = offsets[0] +
311 strides[0] * TJ.planeHeight(0, height, subsamp);
312 offsets[2] = offsets[1] +
313 strides[1] * TJ.planeHeight(1, height, subsamp);
314 }
315
316 yuvAlign = align;
317 setBuf(planes, offsets, width, strides, height, subsamp);
318 }
319
320 /**
321 * Returns the width of the YUV image (or subregion.)
322 *
323 * @return the width of the YUV image (or subregion)
324 */
325 public int getWidth() {
326 if (yuvWidth < 1)
327 throw new IllegalStateException(NO_ASSOC_ERROR);
328 return yuvWidth;
329 }
330
331 /**
332 * Returns the height of the YUV image (or subregion.)
333 *
334 * @return the height of the YUV image (or subregion)
335 */
336 public int getHeight() {
337 if (yuvHeight < 1)
338 throw new IllegalStateException(NO_ASSOC_ERROR);
339 return yuvHeight;
340 }
341
342 /**
343 * Returns the row alignment (in bytes) of the YUV buffer (if this image is
344 * stored in a unified buffer rather than separate image planes.)
345 *
346 * @return the row alignment of the YUV buffer
347 */
348 public int getPad() {
349 if (yuvPlanes == null)
350 throw new IllegalStateException(NO_ASSOC_ERROR);
351 if (yuvAlign < 1 || ((yuvAlign & (yuvAlign - 1)) != 0))
352 throw new IllegalStateException("Image is not stored in a unified buffer");
353 return yuvAlign;
354 }
355
356 /**
357 * Returns the number of bytes per row of each plane in the YUV image.
358 *
359 * @return the number of bytes per row of each plane in the YUV image
360 */
361 public int[] getStrides() {
362 if (yuvStrides == null)
363 throw new IllegalStateException(NO_ASSOC_ERROR);
364 return yuvStrides;
365 }
366
367 /**
368 * Returns the offsets (in bytes) of each plane within the planes of a larger
369 * YUV image.
370 *
371 * @return the offsets (in bytes) of each plane within the planes of a larger
372 * YUV image
373 */
374 public int[] getOffsets() {
375 if (yuvOffsets == null)
376 throw new IllegalStateException(NO_ASSOC_ERROR);
377 return yuvOffsets;
378 }
379
380 /**
381 * Returns the level of chrominance subsampling used in the YUV image. See
382 * {@link TJ#SAMP_444 TJ.SAMP_*}.
383 *
384 * @return the level of chrominance subsampling used in the YUV image
385 */
386 public int getSubsamp() {
387 if (yuvSubsamp < 0 || yuvSubsamp >= TJ.NUMSAMP)
388 throw new IllegalStateException(NO_ASSOC_ERROR);
389 return yuvSubsamp;
390 }
391
392 /**
393 * Returns the YUV image planes. If the image is stored in a unified buffer,
394 * then all image planes will point to that buffer.
395 *
396 * @return the YUV image planes
397 */
398 public byte[][] getPlanes() {
399 if (yuvPlanes == null)
400 throw new IllegalStateException(NO_ASSOC_ERROR);
401 return yuvPlanes;
402 }
403
404 /**
405 * Returns the YUV buffer (if this image is stored in a unified buffer rather
406 * than separate image planes.)
407 *
408 * @return the YUV buffer
409 */
410 public byte[] getBuf() {
411 if (yuvPlanes == null || yuvSubsamp < 0 || yuvSubsamp >= TJ.NUMSAMP)
412 throw new IllegalStateException(NO_ASSOC_ERROR);
413 int nc = (yuvSubsamp == TJ.SAMP_GRAY ? 1 : 3);
414 for (int i = 1; i < nc; i++) {
415 if (yuvPlanes[i] != yuvPlanes[0])
416 throw new IllegalStateException("Image is not stored in a unified buffer");
417 }
418 return yuvPlanes[0];
419 }
420
421 /**
422 * Returns the size (in bytes) of the YUV buffer (if this image is stored in
423 * a unified buffer rather than separate image planes.)
424 *
425 * @return the size (in bytes) of the YUV buffer
426 */
427 public int getSize() {
428 if (yuvPlanes == null || yuvSubsamp < 0 || yuvSubsamp >= TJ.NUMSAMP)
429 throw new IllegalStateException(NO_ASSOC_ERROR);
430 int nc = (yuvSubsamp == TJ.SAMP_GRAY ? 1 : 3);
431 if (yuvAlign < 1)
432 throw new IllegalStateException("Image is not stored in a unified buffer");
433 for (int i = 1; i < nc; i++) {
434 if (yuvPlanes[i] != yuvPlanes[0])
435 throw new IllegalStateException("Image is not stored in a unified buffer");
436 }
437 return TJ.bufSizeYUV(yuvWidth, yuvAlign, yuvHeight, yuvSubsamp);
438 }
439
440 private static int pad(int v, int p) {
441 return (v + p - 1) & (~(p - 1));
442 }
443
444 private long handle = 0;
445 private byte[][] yuvPlanes = null;
446 private int[] yuvOffsets = null;
447 private int[] yuvStrides = null;
448 private int yuvAlign = 1;
449 private int yuvWidth = 0;
450 private int yuvHeight = 0;
451 private int yuvSubsamp = -1;
452 }