1 /* 2 * Copyright (c) 2010, 2014, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 package com.sun.media.jfxmedia.control; 26 27 import java.lang.annotation.Native; 28 import java.nio.ByteBuffer; 29 30 /** 31 * A {@code VideoDataBuffer} describes a single frame of video. 32 */ 33 public interface VideoDataBuffer { 34 /** Plane index used by all packed formats */ 35 @Native public static final int PACKED_FORMAT_PLANE = 0; 36 37 /** Plane index for YCbCr luminance data */ 38 @Native public static final int YCBCR_PLANE_LUMA = 0; 39 /** Plane index for YCbCr red chrominance data */ 40 @Native public static final int YCBCR_PLANE_CR = 1; 41 /** Plane index for YCbCr blue chrominance data */ 42 @Native public static final int YCBCR_PLANE_CB = 2; 43 /** Plane index for YCbCr alpha data, this plane is optional */ 44 @Native public static final int YCBCR_PLANE_ALPHA = 3; 45 46 /** 47 * Retrieve the data buffer for the specified plane. For chunky formats, 48 * pass {@link PACKED_FORMAT_PLANE} as the plane index. If an invalid plane 49 * index is passed this method returns null. 50 * 51 * @param plane The numeric index of the plane 52 * @return the {@code ByteBuffer} containing video data for the specified 53 * plane or null for non-existent or invalid planes 54 */ 55 public ByteBuffer getBufferForPlane(int plane); 56 57 /** 58 * Retrieve the timestamp of the buffer. 59 * 60 * @return The buffer's timestamp. 61 */ 62 public double getTimestamp(); 63 64 /** 65 * Gets the width of the VideoDataBuffer 66 * @return the width of the buffer 67 */ 68 public int getWidth(); 69 70 /** 71 * Gets the height of the VideoDataBuffer 72 * @return the height 73 */ 74 public int getHeight(); 75 76 /** 77 * Gets the width of the image as created by the decoder, this may be larger 78 * than the display width. 79 * @return the number of pixels per row in the image 80 */ 81 public int getEncodedWidth(); 82 83 /** 84 * Gets the height of the image as created by the decoder, this may be larger 85 * than the display height. 86 * @return the number of rows in the image 87 */ 88 public int getEncodedHeight(); 89 90 /** 91 * @return the format of the videoDataBuffer 92 */ 93 public VideoFormat getFormat(); 94 95 /** 96 * Determine if a video buffer has an alpha channel. This merely determines 97 * if the buffer itself has an alpha channel, not if there is any transparency 98 * to the image. 99 * 100 * @return true if an alpha channel is present 101 */ 102 public boolean hasAlpha(); 103 104 /** 105 * @return the number of planes this video buffer contains, or 1 for 106 * non-planar formats 107 */ 108 public int getPlaneCount(); 109 110 /** 111 * Returns the number of bytes in each row of pixels for the specified plane. 112 * 113 * @param planeIndex The numeric index of the plane. 114 * @return Number of bytes that comprises a single row of pixels in the 115 * specified plane. Will return zero if the plane is not in use. 116 */ 117 public int getStrideForPlane(int planeIndex); 118 119 /** 120 * @see getStrideForPlane 121 * @return an array containing the plane strides for all planes 122 */ 123 public int[] getPlaneStrides(); 124 125 /** 126 * Converts the video image to the specified format. You can only convert TO 127 * either {@code ARGB_PRE} or {@code BGRA_PRE}, converting to YCbCr is not 128 * supported here. Once a conversion is done, a reference to the converted 129 * buffer is retained so that future conversions do not need to be performed. 130 * 131 * @param newFormat the video format to convert to 132 * @return new buffer containing a converted copy of the source video image 133 */ 134 public VideoDataBuffer convertToFormat(VideoFormat newFormat); 135 136 /** 137 * Flags a video buffer indicating the contents of the buffer have been 138 * updated and any cached representations need to be updated. 139 */ 140 public void setDirty(); 141 142 /** 143 * Place a hold on a buffer so that it cannot be reused by the buffer pool 144 * from whence it came. Holding a buffer too long may cause additional 145 * buffers to be allocated which will increase memory usage, so one should 146 * take care to release a frame as soon as possible. 147 */ 148 public void holdFrame(); 149 150 /** 151 * Releases a hold previously placed on this frame. When the hold count 152 * reaches zero then the frame will be disposed or reused, thus preventing 153 * memory allocation overhead. 154 */ 155 public void releaseFrame(); 156 }