ppapi/api/ppb_compositor.idl

   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
   8 label 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
  69 interface 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 };