gfx/gl/GLContextProviderImpl.h

   1 /* -*- Mode: C++; tab-width: 20; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  * This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef IN_GL_CONTEXT_PROVIDER_H
   7 #error GLContextProviderImpl.h must only be included from GLContextProvider.h
   8 #endif
   9
  10 #ifndef GL_CONTEXT_PROVIDER_NAME
  11 #error GL_CONTEXT_PROVIDER_NAME not defined
  12 #endif
  13
  14 class GL_CONTEXT_PROVIDER_NAME
  15 {
  16 public:
  17     /**
  18      * Create a context that renders to the surface of the widget that is
  19      * passed in.  The context is always created with an RGB pixel format,
  20      * with no alpha, depth or stencil.  If any of those features are needed,
  21      * either use a framebuffer, or use CreateOffscreen.
  22      *
  23      * This context will attempt to share resources with all other window
  24      * contexts.  As such, it's critical that resources allocated that are not
  25      * needed by other contexts be deleted before the context is destroyed.
  26      *
  27      * The GetSharedContext() method will return non-null if sharing
  28      * was successful.
  29      *
  30      * Note: a context created for a widget /must not/ hold a strong
  31      * reference to the widget; otherwise a cycle can be created through
  32      * a GL layer manager.
  33      *
  34      * @param aWidget Widget whose surface to create a context for
  35      *
  36      * @return Context to use for the window
  37      */
  38     static already_AddRefed<GLContext>
  39     CreateForWindow(nsIWidget* widget);
  40
  41     /**
  42      * Create a context for offscreen rendering.  The target of this
  43      * context should be treated as opaque -- it might be a FBO, or a
  44      * pbuffer, or some other construct.  Users of this GLContext
  45      * should bind framebuffer 0 directly to use this offscreen buffer.
  46      *
  47      * The offscreen context returned by this method will always have
  48      * the ability to be rendered into a context created by a window.
  49      * It might or might not share resources with the global context;
  50      * query GetSharedContext() for a non-null result to check.  If
  51      * resource sharing can be avoided on the target platform, it will
  52      * be, in order to isolate the offscreen context.
  53      *
  54      * @param aSize The initial size of this offscreen context.
  55      * @param aFormat The ContextFormat for this offscreen context.
  56      *
  57      * @return Context to use for offscreen rendering
  58      */
  59     static already_AddRefed<GLContext>
  60     CreateOffscreen(const gfxIntSize& size,
  61                     const SurfaceCaps& caps);
  62
  63     // Just create a context. We'll add offscreen stuff ourselves.
  64     static already_AddRefed<GLContext>
  65     CreateHeadless();
  66
  67     /**
  68      * Create wrapping Gecko GLContext for external gl context.
  69      *
  70      * @param aContext External context which will be wrapped by Gecko GLContext.
  71      * @param aSurface External surface which is used for external context.
  72      *
  73      * @return Wrapping Context to use for rendering
  74      */
  75     static already_AddRefed<GLContext>
  76     CreateWrappingExisting(void* aContext, void* aSurface);
  77
  78     /**
  79      * Get a pointer to the global context, creating it if it doesn't exist.
  80      */
  81     static GLContext*
  82     GetGlobalContext();
  83
  84     /**
  85      * Free any resources held by this Context Provider.
  86      */
  87     static void
  88     Shutdown();
  89 };