1 /* Copyright (c) 2014 The Chromium Authors. All rights reserved.
2 * Use of this source code is governed by a BSD-style license that can be
3 * found in the LICENSE file.
6 /* From ppb_video_decoder.idl modified Mon Sep 8 16:40:15 2014. */
8 #ifndef PPAPI_C_PPB_VIDEO_DECODER_H_
9 #define PPAPI_C_PPB_VIDEO_DECODER_H_
11 #include "ppapi/c/pp_bool.h"
12 #include "ppapi/c/pp_codecs.h"
13 #include "ppapi/c/pp_completion_callback.h"
14 #include "ppapi/c/pp_instance.h"
15 #include "ppapi/c/pp_macros.h"
16 #include "ppapi/c/pp_resource.h"
17 #include "ppapi/c/pp_size.h"
18 #include "ppapi/c/pp_stdint.h"
20 #define PPB_VIDEODECODER_INTERFACE_0_1 "PPB_VideoDecoder;0.1"
21 #define PPB_VIDEODECODER_INTERFACE_0_2 "PPB_VideoDecoder;0.2"
22 #define PPB_VIDEODECODER_INTERFACE PPB_VIDEODECODER_INTERFACE_0_2
26 * This file defines the <code>PPB_VideoDecoder</code> interface.
31 * @addtogroup Interfaces
35 * Video decoder interface.
38 * - Call Create() to create a new video decoder resource.
39 * - Call Initialize() to initialize it with a 3d graphics context and the
40 * desired codec profile.
41 * - Call Decode() continuously (waiting for each previous call to complete) to
42 * push bitstream buffers to the decoder.
43 * - Call GetPicture() continuously (waiting for each previous call to complete)
44 * to pull decoded pictures from the decoder.
45 * - Call Flush() to signal end of stream to the decoder and perform shutdown
47 * - Call Reset() to quickly stop the decoder (e.g. to implement Seek) and wait
48 * for the callback before restarting decoding at another point.
49 * - To destroy the decoder, the plugin should release all of its references to
50 * it. Any pending callbacks will abort before the decoder is destroyed.
52 * Available video codecs vary by platform.
53 * All: theora, vorbis, vp8.
54 * Chrome and ChromeOS: aac, h264.
57 struct PPB_VideoDecoder_0_2 {
59 * Creates a new video decoder resource.
61 * @param[in] instance A <code>PP_Instance</code> identifying the instance
62 * with the video decoder.
64 * @return A <code>PP_Resource</code> corresponding to a video decoder if
65 * successful or 0 otherwise.
67 PP_Resource (*Create)(PP_Instance instance);
69 * Determines if the given resource is a video decoder.
71 * @param[in] resource A <code>PP_Resource</code> identifying a resource.
73 * @return <code>PP_TRUE</code> if the resource is a
74 * <code>PPB_VideoDecoder</code>, <code>PP_FALSE</code> if the resource is
75 * invalid or some other type.
77 PP_Bool (*IsVideoDecoder)(PP_Resource resource);
79 * Initializes a video decoder resource. This should be called after Create()
80 * and before any other functions.
82 * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
84 * @param[in] graphics3d_context A <code>PPB_Graphics3D</code> resource to use
86 * @param[in] profile A <code>PP_VideoProfile</code> specifying the video
88 * @param[in] acceleration A <code>PP_HardwareAcceleration</code> specifying
89 * whether to use a hardware accelerated or a software implementation.
90 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
93 * @return An int32_t containing an error code from <code>pp_errors.h</code>.
94 * Returns PP_ERROR_NOTSUPPORTED if video decoding is not available, or the
95 * requested profile is not supported. In this case, the client may call
96 * Initialize() again with different parameters to find a good configuration.
98 int32_t (*Initialize)(PP_Resource video_decoder,
99 PP_Resource graphics3d_context,
100 PP_VideoProfile profile,
101 PP_HardwareAcceleration acceleration,
102 struct PP_CompletionCallback callback);
104 * Decodes a bitstream buffer. Copies |size| bytes of data from the plugin's
105 * |buffer|. The plugin should wait until the decoder signals completion by
106 * returning PP_OK or by running |callback| before calling Decode() again.
108 * In general, each bitstream buffer should contain a demuxed bitstream frame
109 * for the selected video codec. For example, H264 decoders expect to receive
110 * one AnnexB NAL unit, including the 4 byte start code prefix, while VP8
111 * decoders expect to receive a bitstream frame without the IVF frame header.
113 * If the call to Decode() eventually results in a picture, the |decode_id|
114 * parameter is copied into the returned picture. The plugin can use this to
115 * associate decoded pictures with Decode() calls (e.g. to assign timestamps
116 * or frame numbers to pictures.) This value is opaque to the API so the
117 * plugin is free to pass any value.
119 * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
121 * @param[in] decode_id An optional value, chosen by the plugin, that can be
122 * used to associate calls to Decode() with decoded pictures returned by
124 * @param[in] size Buffer size in bytes.
125 * @param[in] buffer Starting address of buffer.
126 * @param[in] callback A <code>PP_CompletionCallback</code> to be called on
129 * @return An int32_t containing an error code from <code>pp_errors.h</code>.
130 * Returns PP_ERROR_FAILED if the decoder isn't initialized or if a Flush()
131 * or Reset() call is pending.
132 * Returns PP_ERROR_INPROGRESS if there is another Decode() call pending.
133 * Returns PP_ERROR_NOMEMORY if a bitstream buffer can't be created.
134 * Returns PP_ERROR_ABORTED when Reset() is called while Decode() is pending.
136 int32_t (*Decode)(PP_Resource video_decoder,
140 struct PP_CompletionCallback callback);
142 * Gets the next picture from the decoder. The picture is valid after the
143 * decoder signals completion by returning PP_OK or running |callback|. The
144 * plugin can call GetPicture() again after the decoder signals completion.
145 * When the plugin is finished using the picture, it should return it to the
146 * system by calling RecyclePicture().
148 * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
150 * @param[out] picture A <code>PP_VideoPicture</code> to hold the decoded
152 * @param[in] callback A <code>PP_CompletionCallback</code> to be called on
155 * @return An int32_t containing an error code from <code>pp_errors.h</code>.
156 * Returns PP_ERROR_FAILED if the decoder isn't initialized or if a Reset()
158 * Returns PP_ERROR_INPROGRESS if there is another GetPicture() call pending.
159 * Returns PP_ERROR_ABORTED when Reset() is called, or if a call to Flush()
160 * completes while GetPicture() is pending.
162 int32_t (*GetPicture)(PP_Resource video_decoder,
163 struct PP_VideoPicture* picture,
164 struct PP_CompletionCallback callback);
166 * Recycles a picture that the plugin has received from the decoder.
167 * The plugin should call this as soon as it has finished using the texture so
168 * the decoder can decode more pictures.
170 * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
172 * @param[in] picture A <code>PP_VideoPicture</code> to return to
175 void (*RecyclePicture)(PP_Resource video_decoder,
176 const struct PP_VideoPicture* picture);
178 * Flushes the decoder. The plugin should call Flush() when it reaches the
179 * end of its video stream in order to stop cleanly. The decoder will run any
180 * pending Decode() call to completion. The plugin should make no further
181 * calls to the decoder other than GetPicture() and RecyclePicture() until
182 * the decoder signals completion by running |callback|. Just before
183 * completion, any pending GetPicture() call will complete by running its
184 * callback with result PP_ERROR_ABORTED to signal that no more pictures are
185 * available. Any pictures held by the plugin remain valid during and after
186 * the flush and should be recycled back to the decoder.
188 * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
190 * @param[in] callback A <code>PP_CompletionCallback</code> to be called on
193 * @return An int32_t containing an error code from <code>pp_errors.h</code>.
194 * Returns PP_ERROR_FAILED if the decoder isn't initialized.
196 int32_t (*Flush)(PP_Resource video_decoder,
197 struct PP_CompletionCallback callback);
199 * Resets the decoder as quickly as possible. The plugin can call Reset() to
200 * skip to another position in the video stream. After Reset() returns, any
201 * pending calls to Decode() and GetPicture()) abort, causing their callbacks
202 * to run with PP_ERROR_ABORTED. The plugin should not make further calls to
203 * the decoder other than RecyclePicture() until the decoder signals
204 * completion by running |callback|. Any pictures held by the plugin remain
205 * valid during and after the reset and should be recycled back to the
208 * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
210 * @param[in] callback A <code>PP_CompletionCallback</code> to be called on
213 * @return An int32_t containing an error code from <code>pp_errors.h</code>.
214 * Returns PP_ERROR_FAILED if the decoder isn't initialized.
216 int32_t (*Reset)(PP_Resource video_decoder,
217 struct PP_CompletionCallback callback);
220 typedef struct PPB_VideoDecoder_0_2 PPB_VideoDecoder;
222 struct PPB_VideoDecoder_0_1 {
223 PP_Resource (*Create)(PP_Instance instance);
224 PP_Bool (*IsVideoDecoder)(PP_Resource resource);
225 int32_t (*Initialize)(PP_Resource video_decoder,
226 PP_Resource graphics3d_context,
227 PP_VideoProfile profile,
228 PP_Bool allow_software_fallback,
229 struct PP_CompletionCallback callback);
230 int32_t (*Decode)(PP_Resource video_decoder,
234 struct PP_CompletionCallback callback);
235 int32_t (*GetPicture)(PP_Resource video_decoder,
236 struct PP_VideoPicture* picture,
237 struct PP_CompletionCallback callback);
238 void (*RecyclePicture)(PP_Resource video_decoder,
239 const struct PP_VideoPicture* picture);
240 int32_t (*Flush)(PP_Resource video_decoder,
241 struct PP_CompletionCallback callback);
242 int32_t (*Reset)(PP_Resource video_decoder,
243 struct PP_CompletionCallback callback);
249 #endif /* PPAPI_C_PPB_VIDEO_DECODER_H_ */