native_client_sdk/src/libraries/ppapi_simple/ps.h

   1 // Copyright (c) 2012 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 #ifndef PPAPI_SIMPLE_PS_H_
   6 #define PPAPI_SIMPLE_PS_H_
   7
   8 #include "ppapi/c/pp_instance.h"
   9 #include "sdk_util/macros.h"
  10
  11 EXTERN_C_BEGIN
  12
  13 /**
  14  * The ppapi_simple library simplifies the use of the Pepper interfaces by
  15  * providing a more traditional 'C' or 'C++' style framework.  The library
  16  * creates an PSInstance derived object based on the ppapi_cpp library and
  17  * initializes the nacl_io library to provide a POSIX friendly I/O environment.
  18  *
  19  * In order to provide a standard blocking environment, the library will hide
  20  * the actual "Pepper Thread" which is the thread that standard events
  21  * such as window resize, mouse keyboard, or other inputs arrive.  To prevent
  22  * blocking, instead we enqueue these events onto a thread safe linked list
  23  * and expect them to be processed on a new thread.  In addition, the library
  24  * will automatically start a new thread on which can be used effectively
  25  * as a "main" entry point.
  26  *
  27  * For C style development, the PPAPI_SIMPLE_REGISTER_MAIN(XX) macros provide a
  28  * mechanism to register the entry an point for "main".  All events are pushed
  29  * onto an event queue which can then be pulled from this new thread.
  30  * NOTE: The link will still need libstdc++ and libppapi_cpp since the library
  31  * is still creating a C++ object which does the initialization work and
  32  * forwards the events.
  33  *
  34  * For C++ style development, use the ppapi_simple_instance.h,
  35  * ppapi_simple_instance_2d.h, and ppapi_simple_instance_3d.h headers as
  36  * a base class, and overload the appropriate virtual functions such as
  37  * Main, ChangeContext, or Render.
  38  */
  39
  40 /**
  41  * PSGetInstanceId
  42  *
  43  * Return the PP_Instance id of this instance of the module.  This is required
  44  * by most of the Pepper resource creation routines.
  45  */
  46 PP_Instance PSGetInstanceId();
  47
  48
  49 /**
  50  * PSGetInterface
  51  *
  52  * Return the Pepper instance referred to by 'name'.  Will return a pointer
  53  * to the interface, or NULL if not found or not available.
  54  */
  55 const void* PSGetInterface(const char *name);
  56
  57
  58 /**
  59  * PSUserCreateInstance
  60  *
  61  * Prototype for the user provided function which creates and configures
  62  * the instance object.  This function is defined by one of the macros below,
  63  * or by the equivalent macro in one of the other headers.  For 'C'
  64  * development, one of the basic instances which support C callback are used.
  65  * For C++, this function should instantiate the user defined instance.  See
  66  * the two macros below.
  67  */
  68 extern void* PSUserCreateInstance(PP_Instance inst);
  69
  70
  71 /**
  72  * PPAPI_SIMPLE_USE_MAIN
  73  *
  74  * For use with C projects, this macro calls the provided factory with
  75  * configuration information.
  76  */
  77 #define PPAPI_SIMPLE_USE_MAIN(factory, func)   \
  78 void* PSUserCreateInstance(PP_Instance inst) { \
  79   return factory(inst, func);                  \
  80 }
  81
  82
  83 EXTERN_C_END
  84
  85
  86 #endif  // PPAPI_SIMPLE_PS_H_