/* Copyright 2015 The Chromium Authors. All rights reserved. * Use of this source code is governed by a BSD-style license that can be * found in the LICENSE file. */ /** * This file defines the PPB_VideoEncoder interface. */ [generate_thunk] label Chrome { [channel=dev] M42 = 0.1, M44 = 0.2 }; /** * Video encoder interface. * * Typical usage: * - Call Create() to create a new video encoder resource. * - Call GetSupportedFormats() to determine which codecs and profiles are * available. * - Call Initialize() to initialize the encoder for a supported profile. * - Call GetVideoFrame() to get a blank frame and fill it in, or get a video * frame from another resource, e.g. PPB_MediaStreamVideoTrack. * - Call Encode() to push the video frame to the encoder. If an external frame * is pushed, wait for completion to recycle the frame. * - Call GetBitstreamBuffer() continuously (waiting for each previous call to * complete) to pull encoded pictures from the encoder. * - Call RecycleBitstreamBuffer() after consuming the data in the bitstream * buffer. * - To destroy the encoder, the plugin should release all of its references to * it. Any pending callbacks will abort before the encoder is destroyed. * * Available video codecs vary by platform. * All: vp8 (software). * ChromeOS, depending on your device: h264 (hardware), vp8 (hardware) */ interface PPB_VideoEncoder { /** * Creates a new video encoder resource. * * @param[in] instance A PP_Instance identifying the instance * with the video encoder. * * @return A PP_Resource corresponding to a video encoder if * successful or 0 otherwise. */ PP_Resource Create([in] PP_Instance instance); /** * Determines if the given resource is a video encoder. * * @param[in] resource A PP_Resource identifying a resource. * * @return PP_TRUE if the resource is a * PPB_VideoEncoder, PP_FALSE if the resource is * invalid or some other type. */ PP_Bool IsVideoEncoder([in] PP_Resource resource); /** * Gets an array of supported video encoder profiles. * These can be used to choose a profile before calling Initialize(). * * @param[in] video_encoder A PP_Resource identifying the video * encoder. * @param[in] output A PP_ArrayOutput to receive the supported * PP_VideoProfileDescription_0_1 structs. * @param[in] callback A PP_CompletionCallback to be called upon * completion. * * @return If >= 0, the number of supported profiles returned, otherwise an * error code from pp_errors.h. */ int32_t GetSupportedProfiles([in] PP_Resource video_encoder, [in] PP_ArrayOutput output, [in] PP_CompletionCallback callback); /** * Gets an array of supported video encoder profiles. * These can be used to choose a profile before calling Initialize(). * * @param[in] video_encoder A PP_Resource identifying the video * encoder. * @param[in] output A PP_ArrayOutput to receive the supported * PP_VideoProfileDescription structs. * @param[in] callback A PP_CompletionCallback to be called upon * completion. * * @return If >= 0, the number of supported profiles returned, otherwise an * error code from pp_errors.h. */ [version = 0.2] int32_t GetSupportedProfiles([in] PP_Resource video_encoder, [in] PP_ArrayOutput output, [in] PP_CompletionCallback callback); /** * Initializes a video encoder resource. The plugin should call Initialize() * successfully before calling any of the functions below. * * @param[in] video_encoder A PP_Resource identifying the video * encoder. * @param[in] input_format The PP_VideoFrame_Format of the * frames which will be encoded. * @param[in] input_visible_size A PP_Size specifying the * dimensions of the visible part of the input frames. * @param[in] output_profile A PP_VideoProfile specifying the * codec profile of the encoded output stream. * @param[in] acceleration A PP_HardwareAcceleration specifying * whether to use a hardware accelerated or a software implementation. * @param[in] callback A PP_CompletionCallback to be called upon * completion. * * @return An int32_t containing an error code from pp_errors.h. * Returns PP_ERROR_NOTSUPPORTED if video encoding is not available, or the * requested codec profile is not supported. */ int32_t Initialize([in] PP_Resource video_encoder, [in] PP_VideoFrame_Format input_format, [in] PP_Size input_visible_size, [in] PP_VideoProfile output_profile, [in] uint32_t initial_bitrate, [in] PP_HardwareAcceleration acceleration, [in] PP_CompletionCallback callback); /** * Gets the number of input video frames that the encoder may hold while * encoding. If the plugin is providing the video frames, it should have at * least this many available. * * @param[in] video_encoder A PP_Resource identifying the video * encoder. * @return An int32_t containing the number of frames required, or an error * code from pp_errors.h. * Returns PP_ERROR_FAILED if Initialize() has not successfully completed. */ int32_t GetFramesRequired([in] PP_Resource video_encoder); /** * Gets the coded size of the video frames required by the encoder. Coded * size is the logical size of the input frames, in pixels. The encoder may * have hardware alignment requirements that make this different from * |input_visible_size|, as requested in the call to Initialize(). * * @param[in] video_encoder A PP_Resource identifying the video * encoder. * @param[in] coded_size A PP_Size to hold the coded size. * @return An int32_t containing a result code from pp_errors.h. * Returns PP_ERROR_FAILED if Initialize() has not successfully completed. */ int32_t GetFrameCodedSize([in] PP_Resource video_encoder, [out] PP_Size coded_size); /** * Gets a blank video frame which can be filled with video data and passed * to the encoder. * * @param[in] video_encoder A PP_Resource identifying the video * encoder. * @param[out] video_frame A blank PPB_VideoFrame resource. * @param[in] callback A PP_CompletionCallback to be called upon * completion. * * @return An int32_t containing an error code from pp_errors.h. * Returns PP_ERROR_FAILED if Initialize() has not successfully completed. */ int32_t GetVideoFrame([in] PP_Resource video_encoder, [out] PP_Resource video_frame, [in] PP_CompletionCallback callback); /** * Encodes a video frame. * * @param[in] video_encoder A PP_Resource identifying the video * encoder. * @param[in] video_frame The PPB_VideoFrame to be encoded. * @param[in] force_keyframe A PP_Bool> specifying whether the encoder * should emit a key frame for this video frame. * @param[in] callback A PP_CompletionCallback to be called upon * completion. Plugins that pass PPB_VideoFrame resources owned * by other resources should wait for completion before reusing them. * * @return An int32_t containing an error code from pp_errors.h. * Returns PP_ERROR_FAILED if Initialize() has not successfully completed. */ int32_t Encode([in] PP_Resource video_encoder, [in] PP_Resource video_frame, [in] PP_Bool force_keyframe, [in] PP_CompletionCallback callback); /** * Gets the next encoded bitstream buffer from the encoder. * * @param[in] video_encoder A PP_Resource identifying the video * encoder. * @param[out] bitstream_buffer A PP_BitstreamBuffer containing * encoded video data. * @param[in] callback A PP_CompletionCallback to be called upon * completion. The plugin can call GetBitstreamBuffer from the callback in * order to continuously "pull" bitstream buffers from the encoder. * * @return An int32_t containing an error code from pp_errors.h. * Returns PP_ERROR_FAILED if Initialize() has not successfully completed. * Returns PP_ERROR_INPROGRESS if a prior call to GetBitstreamBuffer() has * not completed. */ int32_t GetBitstreamBuffer([in] PP_Resource video_encoder, [out] PP_BitstreamBuffer bitstream_buffer, [in] PP_CompletionCallback callback); /** * Recycles a bitstream buffer back to the encoder. * * @param[in] video_encoder A PP_Resource identifying the video * encoder. * @param[in] bitstream_buffer A PP_BitstreamBuffer that is no * longer needed by the plugin. */ void RecycleBitstreamBuffer([in] PP_Resource video_encoder, [in] PP_BitstreamBuffer bitstream_buffer); /** * Requests a change to encoding parameters. This is only a request, * fulfilled on a best-effort basis. * * @param[in] video_encoder A PP_Resource identifying the video * encoder. * @param[in] bitrate The requested new bitrate, in bits per second. * @param[in] framerate The requested new framerate, in frames per second. */ void RequestEncodingParametersChange([in] PP_Resource video_encoder, [in] uint32_t bitrate, [in] uint32_t framerate); /** * Closes the video encoder, and cancels any pending encodes. Any pending * callbacks will still run, reporting PP_ERROR_ABORTED . It is * not valid to call any encoder functions after a call to this method. * Note: Destroying the video encoder closes it implicitly, * so you are not required to call Close(). * * @param[in] video_encoder A PP_Resource identifying the video * encoder. */ void Close([in] PP_Resource video_encoder); };