1 /* 2 * Copyright 2017 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 package org.webrtc; 12 13 /** 14 * Interface for a video decoder that can be used in WebRTC. All calls to the class will be made on 15 * a single decoding thread. 16 */ 17 public interface VideoDecoder { 18 /** Settings passed to the decoder by WebRTC. */ 19 public class Settings { 20 public final int numberOfCores; 21 public final int width; 22 public final int height; 23 24 @CalledByNative("Settings") Settings(int numberOfCores, int width, int height)25 public Settings(int numberOfCores, int width, int height) { 26 this.numberOfCores = numberOfCores; 27 this.width = width; 28 this.height = height; 29 } 30 } 31 32 /** Additional info for decoding. */ 33 public class DecodeInfo { 34 public final boolean isMissingFrames; 35 public final long renderTimeMs; 36 DecodeInfo(boolean isMissingFrames, long renderTimeMs)37 public DecodeInfo(boolean isMissingFrames, long renderTimeMs) { 38 this.isMissingFrames = isMissingFrames; 39 this.renderTimeMs = renderTimeMs; 40 } 41 } 42 43 public interface Callback { 44 /** 45 * Call to return a decoded frame. Can be called on any thread. 46 * 47 * @param frame Decoded frame 48 * @param decodeTimeMs Time it took to decode the frame in milliseconds or null if not available 49 * @param qp QP value of the decoded frame or null if not available 50 */ onDecodedFrame(VideoFrame frame, Integer decodeTimeMs, Integer qp)51 void onDecodedFrame(VideoFrame frame, Integer decodeTimeMs, Integer qp); 52 } 53 54 /** 55 * The decoder implementation backing this interface is either 1) a Java 56 * decoder (e.g., an Android platform decoder), or alternatively 2) a native 57 * decoder (e.g., a software decoder or a C++ decoder adapter). 58 * 59 * For case 1), createNativeVideoDecoder() should return zero. 60 * In this case, we expect the native library to call the decoder through 61 * JNI using the Java interface declared below. 62 * 63 * For case 2), createNativeVideoDecoder() should return a non-zero value. 64 * In this case, we expect the native library to treat the returned value as 65 * a raw pointer of type webrtc::VideoDecoder* (ownership is transferred to 66 * the caller). The native library should then directly call the 67 * webrtc::VideoDecoder interface without going through JNI. All calls to 68 * the Java interface methods declared below should thus throw an 69 * UnsupportedOperationException. 70 */ 71 @CalledByNative createNativeVideoDecoder()72 default long createNativeVideoDecoder() { 73 return 0; 74 } 75 76 /** 77 * Initializes the decoding process with specified settings. Will be called on the decoding thread 78 * before any decode calls. 79 */ initDecode(Settings settings, Callback decodeCallback)80 @CalledByNative VideoCodecStatus initDecode(Settings settings, Callback decodeCallback); 81 /** 82 * Called when the decoder is no longer needed. Any more calls to decode will not be made. 83 */ release()84 @CalledByNative VideoCodecStatus release(); 85 /** 86 * Request the decoder to decode a frame. 87 */ decode(EncodedImage frame, DecodeInfo info)88 @CalledByNative VideoCodecStatus decode(EncodedImage frame, DecodeInfo info); 89 /** 90 * Should return a descriptive name for the implementation. Gets called once and cached. May be 91 * called from arbitrary thread. 92 */ getImplementationName()93 @CalledByNative String getImplementationName(); 94 } 95