ppapi/api/private/pp_content_decryptor.idl

   1 /* Copyright (c) 2012 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 /**
   7  * The <code>PP_DecryptTrackingInfo</code> struct contains necessary information
   8  * that can be used to associate the decrypted block with a decrypt request
   9  * and/or an input block.
  10  */
  11 [assert_size(16)]
  12 struct PP_DecryptTrackingInfo {
  13   /**
  14    * Client-specified identifier for the associated decrypt request. By using
  15    * this value, the client can associate the decrypted block with a decryption
  16    * request.
  17    */
  18   uint32_t request_id;
  19
  20   /**
  21    * A unique buffer ID to identify a PPB_Buffer_Dev. Unlike a PP_Resource,
  22    * this ID is identical at both the renderer side and the plugin side.
  23    * In <code>PPB_ContentDecryptor_Private</code> calls, this is the ID of the
  24    * buffer associated with the decrypted block/frame/samples.
  25    * In <code>PPP_ContentDecryptor_Private</code> calls, this is the ID of a
  26    * buffer that is no longer need at the renderer side, which can be released
  27    * or recycled by the plugin. This ID can be 0 if there is no buffer to be
  28    * released or recycled.
  29    */
  30   uint32_t buffer_id;
  31
  32   /**
  33    * Timestamp in microseconds of the associated block. By using this value,
  34    * the client can associate the decrypted (and decoded) data with an input
  35    * block. This is needed because buffers may be delivered out of order and
  36    * not in response to the <code>request_id</code> they were provided with.
  37    */
  38   int64_t timestamp;
  39 };
  40
  41 /**
  42  * The <code>PP_DecryptSubsampleDescription</code> struct contains information
  43  * to support subsample decryption.
  44  *
  45  * An input block can be split into several continuous subsamples.
  46  * A <code>PP_DecryptSubsampleEntry</code> specifies the number of clear and
  47  * cipher bytes in each subsample. For example, the following block has three
  48  * subsamples:
  49  *
  50  * |<----- subsample1 ----->|<----- subsample2 ----->|<----- subsample3 ----->|
  51  * |   clear1   |  cipher1  |  clear2  |   cipher2   | clear3 |    cipher3    |
  52  *
  53  * For decryption, all of the cipher bytes in a block should be treated as a
  54  * contiguous (in the subsample order) logical stream. The clear bytes should
  55  * not be considered as part of decryption.
  56  *
  57  * Logical stream to decrypt:   |  cipher1  |   cipher2   |    cipher3    |
  58  * Decrypted stream:            | decrypted1|  decrypted2 |   decrypted3  |
  59  *
  60  * After decryption, the decrypted bytes should be copied over the position
  61  * of the corresponding cipher bytes in the original block to form the output
  62  * block. Following the above example, the decrypted block should be:
  63  *
  64  * |<----- subsample1 ----->|<----- subsample2 ----->|<----- subsample3 ----->|
  65  * |   clear1   | decrypted1|  clear2  |  decrypted2 | clear3 |   decrypted3  |
  66  */
  67 [assert_size(8)]
  68 struct PP_DecryptSubsampleDescription {
  69   /**
  70    * Size in bytes of clear data in a subsample entry.
  71    */
  72   uint32_t clear_bytes;
  73
  74   /**
  75    * Size in bytes of encrypted data in a subsample entry.
  76    */
  77   uint32_t cipher_bytes;
  78 };
  79
  80 /**
  81  * The <code>PP_EncryptedBlockInfo</code> struct contains all the information
  82  * needed to decrypt an encrypted block.
  83  */
  84 [assert_size(248)]
  85 struct PP_EncryptedBlockInfo {
  86   /**
  87    * Information needed by the client to track the block to be decrypted.
  88    */
  89   PP_DecryptTrackingInfo tracking_info;
  90
  91   /**
  92    * Size in bytes of data to be decrypted (data_offset included).
  93    */
  94   uint32_t data_size;
  95
  96   /**
  97    * Size in bytes of data to be discarded before applying the decryption.
  98    */
  99   uint32_t data_offset;
 100
 101   /**
 102    * Key ID of the block to be decrypted.
 103    *
 104    * TODO(xhwang): For WebM the key ID can be as large as 2048 bytes in theory.
 105    * But it's not used in current implementations. If we really need to support
 106    * it, we should move key ID out as a separate parameter, e.g.
 107    * as a <code>PP_Var</code>, or make the whole
 108    * <code>PP_EncryptedBlockInfo</code> as a <code>PP_Resource</code>.
 109    */
 110   uint8_t[64] key_id;
 111   uint32_t key_id_size;
 112
 113   /**
 114    * Initialization vector of the block to be decrypted.
 115    */
 116   uint8_t[16] iv;
 117   uint32_t iv_size;
 118
 119   /**
 120    * Subsample information of the block to be decrypted.
 121    */
 122   PP_DecryptSubsampleDescription[16] subsamples;
 123   uint32_t num_subsamples;
 124
 125   /**
 126    * 4-byte padding to make the size of <code>PP_EncryptedBlockInfo</code>
 127    * a multiple of 8 bytes. The value of this field should not be used.
 128    */
 129   uint32_t padding;
 130 };
 131
 132 /**
 133  * <code>PP_DecryptedFrameFormat</code> contains video frame formats.
 134  */
 135 [assert_size(4)]
 136 enum PP_DecryptedFrameFormat {
 137   PP_DECRYPTEDFRAMEFORMAT_UNKNOWN = 0,
 138   PP_DECRYPTEDFRAMEFORMAT_YV12 = 1,
 139   PP_DECRYPTEDFRAMEFORMAT_I420 = 2
 140 };
 141
 142 /**
 143  * The <code>PP_DecryptResult</code> enum contains decryption and decoding
 144  * result constants.
 145  */
 146 [assert_size(4)]
 147 enum PP_DecryptResult {
 148   /** The decryption (and/or decoding) operation finished successfully. */
 149   PP_DECRYPTRESULT_SUCCESS = 0,
 150   /** The decryptor did not have the necessary decryption key. */
 151   PP_DECRYPTRESULT_DECRYPT_NOKEY = 1,
 152   /** The input was accepted by the decoder but no frame(s) can be produced. */
 153   PP_DECRYPTRESULT_NEEDMOREDATA = 2,
 154   /** An unexpected error happened during decryption. */
 155   PP_DECRYPTRESULT_DECRYPT_ERROR = 3,
 156   /** An unexpected error happened during decoding. */
 157   PP_DECRYPTRESULT_DECODE_ERROR = 4
 158 };
 159
 160 /**
 161  * <code>PP_DecryptedBlockInfo</code> struct contains the decryption result and
 162  * tracking info associated with the decrypted block.
 163  */
 164 [assert_size(24)]
 165 struct PP_DecryptedBlockInfo {
 166   /**
 167    * Result of the decryption (and/or decoding) operation.
 168    */
 169   PP_DecryptResult result;
 170
 171   /**
 172    * Size in bytes of decrypted data, which may be less than the size of the
 173    * corresponding buffer.
 174    */
 175   uint32_t data_size;
 176
 177   /**
 178    * Information needed by the client to track the block to be decrypted.
 179    */
 180   PP_DecryptTrackingInfo tracking_info;
 181 };
 182
 183 /**
 184  * <code>PP_DecryptedFramePlanes</code> provides YUV plane index values for
 185  * accessing plane offsets stored in <code>PP_DecryptedFrameInfo</code>.
 186  */
 187 [assert_size(4)]
 188 enum PP_DecryptedFramePlanes {
 189   PP_DECRYPTEDFRAMEPLANES_Y = 0,
 190   PP_DECRYPTEDFRAMEPLANES_U = 1,
 191   PP_DECRYPTEDFRAMEPLANES_V = 2
 192 };
 193
 194 /**
 195  * <code>PP_DecryptedFrameInfo</code> contains the result of the
 196  * decrypt and decode operation on the associated frame, information required
 197  * to access the frame data in buffer, and tracking info.
 198  */
 199 [assert_size(56)]
 200 struct PP_DecryptedFrameInfo {
 201   /**
 202    * Result of the decrypt and decode operation.
 203    */
 204   PP_DecryptResult result;
 205
 206   /**
 207    * Format of the decrypted frame.
 208    */
 209   PP_DecryptedFrameFormat format;
 210
 211   /**
 212    * Offsets into the buffer resource for accessing video planes.
 213    */
 214   int32_t[3] plane_offsets;
 215
 216   /**
 217    * Stride of each plane.
 218    */
 219   int32_t[3] strides;
 220
 221   /**
 222    * Width of the video frame, in pixels.
 223    */
 224   int32_t width;
 225
 226   /**
 227    * Height of the video frame, in pixels.
 228    */
 229   int32_t height;
 230
 231   /**
 232    * Information needed by the client to track the decrypted frame.
 233    */
 234   PP_DecryptTrackingInfo tracking_info;
 235 };
 236
 237 /**
 238  * <code>PP_AudioCodec</code> contains audio codec type constants.
 239  */
 240 [assert_size(4)]
 241 enum PP_AudioCodec {
 242   PP_AUDIOCODEC_UNKNOWN = 0,
 243   PP_AUDIOCODEC_VORBIS = 1,
 244   PP_AUDIOCODEC_AAC = 2
 245 };
 246
 247 /**
 248  * <code>PP_AudioDecoderConfig</code> contains audio decoder configuration
 249  * information required to initialize audio decoders, and a request ID
 250  * that allows clients to associate a decoder initialization request with a
 251  * status response. Note: When <code>codec</code> requires extra data for
 252  * initialization, the data is sent as a <code>PP_Resource</code> carried
 253  * alongside <code>PP_AudioDecoderConfig</code>.
 254  */
 255  [assert_size(20)]
 256 struct PP_AudioDecoderConfig {
 257   /**
 258    * The audio codec to initialize.
 259    */
 260   PP_AudioCodec codec;
 261
 262   /**
 263    * Number of audio channels.
 264    */
 265   int32_t channel_count;
 266
 267   /**
 268    * Size of each audio channel.
 269    */
 270   int32_t bits_per_channel;
 271
 272   /**
 273    * Audio sampling rate.
 274    */
 275   int32_t samples_per_second;
 276
 277   /**
 278    * Client-specified identifier for the associated audio decoder initialization
 279    * request. By using this value, the client can associate a decoder
 280    * initialization status response with an initialization request.
 281    */
 282   uint32_t request_id;
 283 };
 284
 285 /**
 286  * <code>PP_VideoCodec</code> contains video codec type constants.
 287  */
 288 [assert_size(4)]
 289 enum PP_VideoCodec {
 290   PP_VIDEOCODEC_UNKNOWN = 0,
 291   PP_VIDEOCODEC_VP8 = 1,
 292   PP_VIDEOCODEC_H264 = 2
 293 };
 294
 295 /**
 296  * <code>PP_VideoCodecProfile</code> contains video codec profile type
 297  * constants required for video decoder configuration.
 298  *.
 299  */
 300 [assert_size(4)]
 301 enum PP_VideoCodecProfile {
 302   PP_VIDEOCODECPROFILE_UNKNOWN = 0,
 303   PP_VIDEOCODECPROFILE_VP8_MAIN = 1,
 304   PP_VIDEOCODECPROFILE_H264_BASELINE = 2,
 305   PP_VIDEOCODECPROFILE_H264_MAIN = 3,
 306   PP_VIDEOCODECPROFILE_H264_EXTENDED = 4,
 307   PP_VIDEOCODECPROFILE_H264_HIGH = 5,
 308   PP_VIDEOCODECPROFILE_H264_HIGH_10 = 6,
 309   PP_VIDEOCODECPROFILE_H264_HIGH_422 = 7,
 310   PP_VIDEOCODECPROFILE_H264_HIGH_444_PREDICTIVE = 8
 311 };
 312
 313 /**
 314  * <code>PP_VideoDecoderConfig</code> contains video decoder configuration
 315  * information required to initialize video decoders, and a request ID
 316  * that allows clients to associate a decoder initialization request with a
 317  * status response. Note: When <code>codec</code> requires extra data for
 318  * initialization, the data is sent as a <code>PP_Resource</code> carried
 319  * alongside <code>PP_VideoDecoderConfig</code>.
 320  */
 321 [assert_size(24)]
 322 struct PP_VideoDecoderConfig {
 323   /**
 324    * The video codec to initialize.
 325    */
 326   PP_VideoCodec codec;
 327
 328   /**
 329    * Profile to use when initializing the video codec.
 330    */
 331   PP_VideoCodecProfile profile;
 332
 333   /**
 334    * Output video format.
 335    */
 336   PP_DecryptedFrameFormat format;
 337
 338   /**
 339    * Width of decoded video frames, in pixels.
 340    */
 341   int32_t width;
 342
 343   /**
 344    * Height of decoded video frames, in pixels.
 345    */
 346   int32_t height;
 347
 348   /**
 349    * Client-specified identifier for the associated video decoder initialization
 350    * request. By using this value, the client can associate a decoder
 351    * initialization status response with an initialization request.
 352    */
 353   uint32_t request_id;
 354 };
 355
 356 /**
 357  * <code>PP_DecryptorStreamType</code> contains stream type constants.
 358  */
 359 [assert_size(4)]
 360 enum PP_DecryptorStreamType {
 361   PP_DECRYPTORSTREAMTYPE_AUDIO = 0,
 362   PP_DECRYPTORSTREAMTYPE_VIDEO = 1
 363 };