ppapi/c/ppb_compositor.h

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