1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
/* Copyright (c) 2014 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.
*/
/* From ppb_video_decoder.idl modified Tue May 6 05:19:45 2014. */
#ifndef PPAPI_C_PPB_VIDEO_DECODER_H_
#define PPAPI_C_PPB_VIDEO_DECODER_H_
#include "ppapi/c/pp_bool.h"
#include "ppapi/c/pp_codecs.h"
#include "ppapi/c/pp_completion_callback.h"
#include "ppapi/c/pp_instance.h"
#include "ppapi/c/pp_macros.h"
#include "ppapi/c/pp_resource.h"
#include "ppapi/c/pp_size.h"
#include "ppapi/c/pp_stdint.h"
#define PPB_VIDEODECODER_INTERFACE_0_1 "PPB_VideoDecoder;0.1" /* dev */
/**
* @file
* This file defines the <code>PPB_VideoDecoder</code> interface.
*/
/**
* @addtogroup Interfaces
* @{
*/
/**
* Video decoder interface.
*
* Typical usage:
* - Call Create() to create a new video decoder resource.
* - Call Initialize() to initialize it with a 3d graphics context and the
* desired codec profile.
* - Call Decode() continuously (waiting for each previous call to complete) to
* push bitstream buffers to the decoder.
* - Call GetPicture() continuously (waiting for each previous call to complete)
* to pull decoded pictures from the decoder.
* - Call Flush() to signal end of stream to the decoder and perform shutdown
* when it completes.
* - Call Reset() to quickly stop the decoder (e.g. to implement Seek) and wait
* for the callback before restarting decoding at another point.
* - To destroy the decoder, the plugin should release all of its references to
* it. Any pending callbacks will abort before the decoder is destroyed.
*
* Available video codecs vary by platform.
* All: theora, vorbis, vp8.
* Chrome and ChromeOS: aac, h264.
* ChromeOS: mpeg4.
*/
struct PPB_VideoDecoder_0_1 { /* dev */
/**
* Creates a new video decoder resource.
*
* @param[in] instance A <code>PP_Instance</code> identifying the instance
* with the video decoder.
*
* @return A <code>PP_Resource</code> corresponding to a video decoder if
* successful or 0 otherwise.
*/
PP_Resource (*Create)(PP_Instance instance);
/**
* Determines if the given resource is a video decoder.
*
* @param[in] resource A <code>PP_Resource</code> identifying a resource.
*
* @return <code>PP_TRUE</code> if the resource is a
* <code>PPB_VideoDecoder</code>, <code>PP_FALSE</code> if the resource is
* invalid or some other type.
*/
PP_Bool (*IsVideoDecoder)(PP_Resource resource);
/**
* Initializes a video decoder resource. This should be called after Create()
* and before any other functions.
*
* @param[in] video_decoder A <code>PP_Resource</code> identifying the video
* decoder.
* @param[in] graphics3d_context A <code>PPB_Graphics3D</code> resource to use
* during decoding.
* @param[in] profile A <code>PP_VideoProfile</code> specifying the video
* codec profile.
* @param[in] allow_software_fallback A <code>PP_Bool</code> specifying
* whether the decoder can fall back to software decoding if a suitable
* hardware decoder isn't available.
* @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
* completion.
*
* @return An int32_t containing an error code from <code>pp_errors.h</code>.
* Returns PP_ERROR_NOTSUPPORTED if video decoding is not available, or the
* requested profile is not supported. In this case, the client may call
* Initialize() again with different parameters to find a good configuration.
*/
int32_t (*Initialize)(PP_Resource video_decoder,
PP_Resource graphics3d_context,
PP_VideoProfile profile,
PP_Bool allow_software_fallback,
struct PP_CompletionCallback callback);
/**
* Decodes a bitstream buffer. Copies |size| bytes of data from the plugin's
* |buffer|. The plugin should maintain the buffer and not call Decode() again
* until the decoder signals completion by returning PP_OK or by running
* |callback|.
*
* In general, each bitstream buffer should contain a demuxed bitstream frame
* for the selected video codec. For example, H264 decoders expect to receive
* one AnnexB NAL unit, including the 4 byte start code prefix, while VP8
* decoders expect to receive a bitstream frame without the IVF frame header.
*
* If the call to Decode() eventually results in a picture, the |decode_id|
* parameter is copied into the returned picture. The plugin can use this to
* associate decoded pictures with Decode() calls (e.g. to assign timestamps
* or frame numbers to pictures.) This value is opaque to the API so the
* plugin is free to pass any value.
*
* @param[in] video_decoder A <code>PP_Resource</code> identifying the video
* decoder.
* @param[in] decode_id An optional value, chosen by the plugin, that can be
* used to associate calls to Decode() with decoded pictures returned by
* GetPicture().
* @param[in] size Buffer size in bytes.
* @param[in] buffer Starting address of buffer.
* @param[in] callback A <code>PP_CompletionCallback</code> to be called on
* completion.
*
* @return An int32_t containing an error code from <code>pp_errors.h</code>.
*/
int32_t (*Decode)(PP_Resource video_decoder,
uint32_t decode_id,
uint32_t size,
const void* buffer,
struct PP_CompletionCallback callback);
/**
* Gets the next picture from the decoder. The picture is valid after the
* decoder signals completion by returning PP_OK or running |callback|. The
* plugin can call GetPicture() again after the decoder signals completion.
* When the plugin is finished using the picture, it should return it to the
* system by calling RecyclePicture().
*
* @param[in] video_decoder A <code>PP_Resource</code> identifying the video
* decoder.
* @param[out] picture A <code>PP_VideoPicture</code> to hold the decoded
* picture.
* @param[in] callback A <code>PP_CompletionCallback</code> to be called on
* completion.
*
* @return An int32_t containing an error code from <code>pp_errors.h</code>.
* Returns PP_OK if a picture is available.
* Returns PP_ERROR_ABORTED when Reset() is called, or if a call to Flush()
* completes while GetPicture() is pending.
*/
int32_t (*GetPicture)(PP_Resource video_decoder,
struct PP_VideoPicture* picture,
struct PP_CompletionCallback callback);
/**
* Recycles a picture that the plugin has received from the decoder.
* The plugin should call this as soon as it has finished using the texture so
* the decoder can decode more pictures.
*
* @param[in] video_decoder A <code>PP_Resource</code> identifying the video
* decoder.
* @param[in] picture A <code>PP_VideoPicture</code> to return to
* the decoder.
*/
void (*RecyclePicture)(PP_Resource video_decoder,
const struct PP_VideoPicture* picture);
/**
* Flushes the decoder. The plugin should call this when it reaches the end of
* its video stream in order to stop cleanly. The decoder will run all pending
* calls to completion. The plugin should make no further calls to the decoder
* other than GetPicture() and RecyclePicture() until the decoder signals
* completion by running the callback. Just before completion, any pending
* GetPicture() call will complete by running the callback with result
* PP_ERROR_ABORTED to signal that no more pictures are available.
*
* @param[in] video_decoder A <code>PP_Resource</code> identifying the video
* decoder.
* @param[in] callback A <code>PP_CompletionCallback</code> to be called on
* completion.
*
* @return An int32_t containing an error code from <code>pp_errors.h</code>.
*/
int32_t (*Flush)(PP_Resource video_decoder,
struct PP_CompletionCallback callback);
/**
* Resets the decoder as quickly as possible. The plugin can call Reset() to
* skip to another position in the video stream. Pending calls to Decode() and
* GetPicture()) are immediately aborted, causing their callbacks to run with
* PP_ERROR_ABORTED. The plugin should not make any further calls to the
* decoder until the decoder signals completion by running |callback|.
*
* @param[in] video_decoder A <code>PP_Resource</code> identifying the video
* decoder.
* @param[in] callback A <code>PP_CompletionCallback</code> to be called on
* completion.
*
* @return An int32_t containing an error code from <code>pp_errors.h</code>.
*/
int32_t (*Reset)(PP_Resource video_decoder,
struct PP_CompletionCallback callback);
};
/**
* @}
*/
#endif /* PPAPI_C_PPB_VIDEO_DECODER_H_ */
|
