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.
4 */
5
6/* From ppb_video_decoder.idl modified Mon Sep  8 16:40:15 2014. */
7
8#ifndef PPAPI_C_PPB_VIDEO_DECODER_H_
9#define PPAPI_C_PPB_VIDEO_DECODER_H_
10
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"
19
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
23
24/**
25 * @file
26 * This file defines the <code>PPB_VideoDecoder</code> interface.
27 */
28
29
30/**
31 * @addtogroup Interfaces
32 * @{
33 */
34/**
35 * Video decoder interface.
36 *
37 * Typical usage:
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
46 *   when it completes.
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.
51 *
52 * Available video codecs vary by platform.
53 * All: theora, vorbis, vp8.
54 * Chrome and ChromeOS: aac, h264.
55 * ChromeOS: mpeg4.
56 */
57struct PPB_VideoDecoder_0_2 {
58  /**
59   * Creates a new video decoder resource.
60   *
61   * @param[in] instance A <code>PP_Instance</code> identifying the instance
62   * with the video decoder.
63   *
64   * @return A <code>PP_Resource</code> corresponding to a video decoder if
65   * successful or 0 otherwise.
66   */
67  PP_Resource (*Create)(PP_Instance instance);
68  /**
69   * Determines if the given resource is a video decoder.
70   *
71   * @param[in] resource A <code>PP_Resource</code> identifying a resource.
72   *
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.
76   */
77  PP_Bool (*IsVideoDecoder)(PP_Resource resource);
78  /**
79   * Initializes a video decoder resource. This should be called after Create()
80   * and before any other functions.
81   *
82   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
83   * decoder.
84   * @param[in] graphics3d_context A <code>PPB_Graphics3D</code> resource to use
85   * during decoding.
86   * @param[in] profile A <code>PP_VideoProfile</code> specifying the video
87   * codec profile.
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
91   * completion.
92   *
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.
97   */
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);
103  /**
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.
107   *
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.
112   *
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.
118   *
119   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
120   * decoder.
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
123   * GetPicture().
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
127   * completion.
128   *
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.
135   */
136  int32_t (*Decode)(PP_Resource video_decoder,
137                    uint32_t decode_id,
138                    uint32_t size,
139                    const void* buffer,
140                    struct PP_CompletionCallback callback);
141  /**
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().
147   *
148   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
149   * decoder.
150   * @param[out] picture A <code>PP_VideoPicture</code> to hold the decoded
151   * picture.
152   * @param[in] callback A <code>PP_CompletionCallback</code> to be called on
153   * completion.
154   *
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()
157   * call is pending.
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.
161   */
162  int32_t (*GetPicture)(PP_Resource video_decoder,
163                        struct PP_VideoPicture* picture,
164                        struct PP_CompletionCallback callback);
165  /**
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.
169   *
170   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
171   * decoder.
172   * @param[in] picture A <code>PP_VideoPicture</code> to return to
173   * the decoder.
174   */
175  void (*RecyclePicture)(PP_Resource video_decoder,
176                         const struct PP_VideoPicture* picture);
177  /**
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.
187   *
188   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
189   * decoder.
190   * @param[in] callback A <code>PP_CompletionCallback</code> to be called on
191   * completion.
192   *
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.
195   */
196  int32_t (*Flush)(PP_Resource video_decoder,
197                   struct PP_CompletionCallback callback);
198  /**
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
206   * decoder.
207   *
208   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
209   * decoder.
210   * @param[in] callback A <code>PP_CompletionCallback</code> to be called on
211   * completion.
212   *
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.
215   */
216  int32_t (*Reset)(PP_Resource video_decoder,
217                   struct PP_CompletionCallback callback);
218};
219
220typedef struct PPB_VideoDecoder_0_2 PPB_VideoDecoder;
221
222struct 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,
231                    uint32_t decode_id,
232                    uint32_t size,
233                    const void* buffer,
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);
244};
245/**
246 * @}
247 */
248
249#endif  /* PPAPI_C_PPB_VIDEO_DECODER_H_ */
250
251