1/* Copyright 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[generate_thunk]
7
8label Chrome {
9  [channel=dev] M37 = 0.1
10};
11
12/**
13 * Defines the <code>PPB_Compositor</code> interface. Used for setting
14 * <code>PPB_CompositorLayer</code> layers to the Chromium compositor for
15 * compositing. This allows a plugin to combine different sources of visual
16 * data efficiently, such as <code>PPB_ImageData</code> images and
17 * OpenGL textures. See also <code>PPB_CompositorLayer</code> for more
18 * information.
19 * This interface is still in development (Dev API status) and may change,
20 * so is only supported on Dev channel and Canary currently.
21 *
22 * <strong>Example usage from plugin code:</strong>
23 *
24 * <strong>Setup:</strong>
25 * @code
26 * PP_Resource compositor;
27 * compositor = compositor_if->Create(instance);
28 * instance_if->BindGraphics(instance, compositor);
29 * @endcode
30 *
31 * <strong>Setup layer stack:</strong>
32 * @code
33 * PP_Resource color_layer = compositor_if->AddLayer(compositor);
34 * PP_Resource texture_layer = compositor_if->AddLayer(compositor);
35 * @endcode
36 *
37 * <strong> Present one frame:</strong>
38 * layer_if->SetColor(color_layer, 255, 255, 0, 255, PP_MakeSize(400, 400));
39 * PP_CompletionCallback release_callback = {
40 *   TextureReleasedCallback, 0, PP_COMPLETIONCALLBACK_FLAG_NONE,
41 * };
42 * layer_if->SetTexture(texture_layer, graphics3d, texture_id,
43 *                      PP_MakeSize(300, 300), release_callback);
44 *
45 * PP_CompletionCallback callback = {
46 *   DidFinishCommitLayersCallback,
47 *   (void*) texture_id,
48 *   PP_COMPLETIONCALLBACK_FLAG_NONE,
49 * };
50 * compositor_if->CommitLayers(compositor, callback);
51 * @endcode
52 *
53 * <strong>release callback</strong>
54 * void ReleaseCallback(int32_t result, void* user_data) {
55 *   if (result == PP_OK) {
56 *     uint32_t texture_id = (uint32_t) user_data;
57 *     // reuse the texture or delete it.
58 *   }
59 * }
60 *
61 * <strong>Shutdown:</strong>
62 * @code
63 * core->ReleaseResource(color_layer);
64 * core->ReleaseResource(texture_layer);
65 * core->ReleaseResource(compositor);
66 * @endcode
67 */
68
69interface PPB_Compositor {
70  /**
71   * Determines if a resource is a compositor resource.
72   *
73   * @param[in] resource The <code>PP_Resource</code> to test.
74   *
75   * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
76   * resource is a compositor resource or <code>PP_FALSE</code> otherwise.
77   */
78  PP_Bool IsCompositor([in] PP_Resource resource);
79
80  /**
81   * Creates a Compositor resource.
82   *
83   * @param[in] instance A <code>PP_Instance</code> identifying one instance
84   * of a module.
85   *
86   * @return A <code>PP_Resource</code> containing the compositor resource if
87   * sucessful or 0 otherwise.
88   */
89  PP_Resource Create([in] PP_Instance instance);
90
91  /**
92   * Creates a new <code>PPB_CompositorLayer</code> and adds it to the end
93   * of the layer stack. A <code>PP_Resource</code> containing the layer is
94   * returned. It is uninitialized, <code>SetColor()</code>,
95   * <code>SetTexture</code> or <code>SetImage</code> should be used to
96   * initialize it. The layer will appear above other pre-existing layers.
97   * If <code>ResetLayers</code> is called or the <code>PPB_Compositor</code> is
98   * released, the returned layer will be invalidated, and any further calls on
99   * the layer will return <code>PP_ERROR_BADRESOURCE</code>.
100   *
101   * param[in] compositor A <code>PP_Resource</code> corresponding to
102   * a compositor layer resource.
103   *
104   * @return A <code>PP_Resource</code> containing the compositor layer
105   * resource if sucessful or 0 otherwise.
106   */
107  PP_Resource AddLayer([in] PP_Resource compositor);
108
109  /**
110   * Commits layers added by <code>AddLayer()</code> to the chromium compositor.
111   *
112   * param[in] compositor A <code>PP_Resource</code> corresponding to
113   * a compositor layer resource.
114   * @param[in] cc A <code>PP_CompletionCallback</code> to be called when
115   * layers have been represented on screen.
116   *
117   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
118   */
119  int32_t CommitLayers([in] PP_Resource compositor,
120                       [in] PP_CompletionCallback cc);
121
122  /**
123   * Resets layers added by <code>AddLayer()</code>.
124   *
125   * param[in] compositor A <code>PP_Resource</code> corresponding to
126   * a compositor layer resource.
127   *
128   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
129   */
130  int32_t ResetLayers([in] PP_Resource compositor);
131};
132