org.gstreamer.event.QOSEvent Maven / Gradle / Ivy
Show all versions of gstreamer-java Show documentation
/*
* Copyright (c) 2008 Wayne Meissner
* Copyright (C) 1999,2000 Erik Walthinsen
* 2000 Wim Taymans
* 2005 Wim Taymans
*
* This file is part of gstreamer-java.
*
* This code is free software: you can redistribute it and/or modify it under
* the terms of the GNU Lesser General Public License version 3 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
* version 3 for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* version 3 along with this work. If not, see The QOS event is generated in an element that wants an upstream
* element to either reduce or increase its rate because of
* high/low CPU load or other resource usage such as network performance.
* Typically sinks generate these events for each buffer they receive.
*
*/
public class QOSEvent extends Event {
private static interface API extends com.sun.jna.Library {
Pointer ptr_gst_event_new_qos(double proportion, long diff, ClockTime timestamp);
void gst_event_parse_qos(Event event, double[] proportion, long[] diff, ClockTime[] timestamp);
}
private static final API gst = GstNative.load(API.class);
/**
* This constructor is for internal use only.
* @param init initialization data.
*/
public QOSEvent(Initializer init) {
super(init);
}
/**
* Creates a new quality-of-service event.
*
* proportion indicates the real-time performance of the streaming in the
* element that generated the QoS event (usually the sink). The value is
* generally computed based on more long term statistics about the streams
* timestamps compared to the clock.
*
* A value < 1.0 indicates that the upstream element is producing data faster
* than real-time. A value > 1.0 indicates that the upstream element is not
* producing data fast enough. 1.0 is the ideal proportion value. The
* proportion value can safely be used to lower or increase the quality of
* the element.
*
* difference is the difference against the clock in running time of the last
* buffer that caused the element to generate the QOS event. A negative value
* means that the buffer with timestamp arrived in time. A positive value
* indicates how late the buffer with timestamp was.
*
* timestamp is the timestamp of the last buffer that cause the element
* to generate the QOS event. It is expressed in running time and thus an ever
* increasing value.
*
* The upstream element can use the diff and timestamp values to decide
* whether to process more buffers. For positive difference, all buffers with
* timestamp <= timestamp + difference will certainly arrive late in the sink
* as well.
*
* The application can use general event probes to intercept the QoS
* event and implement custom application specific QoS handling.
*
* @param proportion the proportion of the qos message
* @param difference the time difference of the last Clock sync
* @param timestamp the timestamp of the buffer
*/
public QOSEvent(double proportion, long difference, ClockTime timestamp) {
super(initializer(gst.ptr_gst_event_new_qos(proportion, difference, timestamp)));
}
/**
* Gets the proportion value of this event.
*
* The proportion indicates the real-time performance of the streaming in the
* element that generated the QoS event (usually the sink). The value is
* generally computed based on more long term statistics about the streams
* timestamps compared to the clock.
*
* @return the proportion.
*/
public double getProportion() {
double[] p = { 0d };
gst.gst_event_parse_qos(this, p, null, null);
return p[0];
}
/**
* Gets the difference value of this event.
*
* This is the difference against the clock in running time of the last
* buffer that caused the element to generate the QOS event. A negative value
* means that the buffer with timestamp arrived in time. A positive value
* indicates how late the buffer with timestamp was.
*
* @return the difference.
*/
public long getDifference() {
long[] diff = { 0 };
gst.gst_event_parse_qos(this, null, diff, null);
return diff[0];
}
/**
* Gets the timestamp from this event.
*
* This is the timestamp of the last buffer that caused the element to generate the
* QOS event. It is expressed in running time and thus an ever increasing value.
*
* @return the timestamp
*/
public ClockTime getTimestamp() {
ClockTime[] timestamp = new ClockTime[1];
gst.gst_event_parse_qos(this, null, null, timestamp);
return timestamp[0];
}
}