Package org.openni

# Class VideoFrameRef

java.lang.Object
org.openni.VideoFrameRef

public class VideoFrameRef extends Object
The `VideoFrameRef` class encapsulates a single video frame - the output of a `VideoStream` at a specific time. The data contained will be a single frame of color, IR, or depth video, along with associated meta data. An object of type `VideoFrameRef` does not actually hold the data of the frame, but only a reference to it. OpenNI uses a ref-count to decide when the data buffer can be freed. Once the frame is no longer needed, it can be released by calling the `release()` method. Although the finalization process of the garbage collector also releases the reference, it is preferable to manually release it by calling this method rather than to rely on a finalization process which may not run to completion for a long period of time. The usual way to obtain `VideoFrameRef` objects is by a call to `VideoStream.readFrame()`. Please note that the returned frame holds native memory. Although the finalization process of the garbage collector also disposes of the same system resources, it is preferable to manually free the associated resources by calling this method rather than to rely on a finalization process which may not run to completion for a long period of time. All data references by a `VideoFrameRef` is stored as a primitive array of pixels. Each pixel will be of a type according to the configured pixel format (see `VideoMode`).

## Method Summary

Modifier and Type
Method
Description
`protected void`
`finalize()`
`int`
`getCropOriginX()`
Indicates the X coordinate of the upper left corner of the crop window.
`int`
`getCropOriginY()`
Indicates the Y coordinate of the upper left corner of the crop window.
`boolean`
`getCroppingEnabled()`
Indicates whether cropping was enabled when the frame was produced.
`final ByteBuffer`
`getData()`
Getter function for the array of data pointed to by this object.
`int`
`getFrameIndex()`
Frames are provided sequential frame ID numbers by the sensor that produced them.
`int`
`getHeight()`
Gives the current height of this frame, measured in pixels.
`SensorType`
`getSensorType()`
Getter function for the sensor type used to produce this frame.
`int`
`getStrideInBytes()`
Gives the length of one row of pixels, measured in bytes.
`long`
`getTimestamp()`
Provides a timestamp for the frame.
`final VideoMode`
`getVideoMode()`
Returns a reference to the `VideoMode` object assigned to this frame.
`int`
`getWidth()`
Gives the current width of this frame, measured in pixels.
`void`
`release()`
Release the reference to the frame.

### Methods inherited from class java.lang.Object

`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Method Details

### getData

public final ByteBuffer getData()
Getter function for the array of data pointed to by this object.

Returns:
  ByteBuffer object to the actual frame data array. Type of data can be determined according to the pixel format (can be obtained by calling `getVideoMode()`).

### getSensorType

public SensorType getSensorType()
Getter function for the sensor type used to produce this frame. Used to determine whether this is an IR, Color or Depth frame. See the `SensorType` enumeration for all possible return values from this function.

Returns:
  The type of sensor used to produce this frame.

### getVideoMode

public final VideoMode getVideoMode()
Returns a reference to the `VideoMode` object assigned to this frame. This object describes the video mode the sensor was configured to when the frame was produced and can be used to determine the pixel format and resolution of the data. It will also provide the frame rate that the sensor was running at when it recorded this frame.

Returns:
  Reference to the `VideoMode` assigned to this frame.

### getTimestamp

public long getTimestamp()
Provides a timestamp for the frame. The 'zero' point for this stamp is implementation specific, but all streams from the same device are guaranteed to use the same zero. This value can therefore be used to compute time deltas between frames from the same device, regardless of whether they are from the same stream.

Returns:
  Timestamp of frame, measured in microseconds from an arbitrary zero

### getFrameIndex

public int getFrameIndex()
Frames are provided sequential frame ID numbers by the sensor that produced them. If frame synchronization has been enabled for a device via `Device.setDepthColorSyncEnabled(boolean)`, then frame numbers for corresponding frames of depth and color are guaranteed to match. If frame synchronization is not enabled, then there is no guarantee of matching frame indexes between `VideoStream` "VideoStreams". In the latter case, applications should use timestamps instead of frame indexes to align frames in time.

Returns:
  Index number for this frame.

### getWidth

public int getWidth()
Gives the current width of this frame, measured in pixels. If cropping is enabled, this will be the width of the cropping window. If cropping is not enabled, then this will simply be equal to the X resolution of the `VideoMode` used to produce this frame.

Returns:
  Width of this frame in pixels.

### getHeight

public int getHeight()
Gives the current height of this frame, measured in pixels. If cropping is enabled, this will be the length of the cropping window. If cropping is not enabled, then this will simply be equal to the Y resolution of the `VideoMode` used to produce this frame.

### getCroppingEnabled

public boolean getCroppingEnabled()
Indicates whether cropping was enabled when the frame was produced.

Returns:
  true if cropping is enabled, false otherwise

### getCropOriginX

public int getCropOriginX()
Indicates the X coordinate of the upper left corner of the crop window.

Returns:
  Distance of crop origin from left side of image, in pixels.

### getCropOriginY

public int getCropOriginY()
Indicates the Y coordinate of the upper left corner of the crop window.

Returns:
  Distance of crop origin from top of image, in pixels.

### getStrideInBytes

public int getStrideInBytes()
Gives the length of one row of pixels, measured in bytes. Primarily useful for indexing the array which contains the data.

Returns:
  Stride of the array which contains the image for this frame, in bytes

### release

public void release()
Release the reference to the frame. Once this method is called, the object becomes invalid, and no method should be called other than the assignment operator, or passing this object to a `VideoStream`::readFrame() call. Although the finalization process of the garbage collector also releases the reference, it is preferable to manually release it by calling this method rather than to rely on a finalization process which may not run to completion for a long period of time.

### finalize

protected void finalize() throws Throwable

Overrides:
  `finalize` in class `Object`
Throws:
  `Throwable`