1/* Copyright (c) 2013 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 * This file defines the <code>PPB_VideoDestination_Private</code> interface
8 * for a video destination resource, which sends video frames to a MediaStream
9 * video track in the browser.
10 */
11
12 label Chrome {
13   M28 = 0.1
14 };
15
16/**
17 * The <code>PPB_VideoDestination_Private</code> interface contains pointers to
18 * several functions for creating video destination resources and using them to
19 * send video frames to a MediaStream video track in the browser.
20 */
21interface PPB_VideoDestination_Private {
22  /**
23   * Creates a video destination resource.
24   *
25   * @param[in] instance A <code>PP_Instance</code> identifying an instance of
26   * a module.
27   *
28   * @return A <code>PP_Resource</code> with a nonzero ID on success or zero on
29   * failure. Failure means the instance was invalid.
30   */
31  PP_Resource Create([in] PP_Instance instance);
32
33  /**
34   * Determines if a resource is a video destination resource.
35   *
36   * @param[in] resource The <code>PP_Resource</code> to test.
37   *
38   * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
39   * resource is a video destination resource or <code>PP_FALSE</code>
40   * otherwise.
41   */
42  PP_Bool IsVideoDestination([in] PP_Resource resource);
43
44  /**
45   * Opens a video destination for putting frames.
46   *
47   * @param[in] destination A <code>PP_Resource</code> corresponding to a video
48   * destination resource.
49   * @param[in] stream_url A <code>PP_Var</code> string holding a URL
50   * identifying a MediaStream.
51   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
52   * completion of Open().
53   *
54   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
55   * Returns PP_ERROR_BADRESOURCE if destination isn't a valid video
56   * destination.
57   * Returns PP_ERROR_INPROGRESS if destination is already open.
58   * Returns PP_ERROR_FAILED if the MediaStream doesn't exist or if there is
59   * some other browser error.
60   */
61  int32_t Open([in] PP_Resource destination,
62               [in] PP_Var stream_url,
63               [in] PP_CompletionCallback callback);
64
65  /**
66   * Puts a frame to the video destination.
67   *
68   * After this call, you should take care to release your references to the
69   * image embedded in the video frame. If you paint to the image after
70   * PutFame(), there is the possibility of artifacts because the browser may
71   * still be copying the frame to the stream.
72   *
73   * @param[in] destination A <code>PP_Resource</code> corresponding to a video
74   * destination resource.
75   * @param[in] frame A <code>PP_VideoFrame_Private</code> holding the video
76   * frame to send to the destination.
77   *
78   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
79   * Returns PP_ERROR_BADRESOURCE if destination isn't a valid video
80   * destination.
81   * Returns PP_ERROR_FAILED if destination is not open, if the video frame has
82   * an invalid image data resource, or if some other browser error occurs.
83   */
84  int32_t PutFrame([in] PP_Resource destination,
85                   [in] PP_VideoFrame_Private frame);
86
87  /**
88   * Closes the video destination.
89   *
90   * @param[in] destination A <code>PP_Resource</code> corresponding to a video
91   * destination.
92   */
93  void Close([in] PP_Resource destination);
94};
95
96