Home | History | Annotate | Download | only in api 
      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 };
    132