Document wxBK_HITTEST_XXX values.

[wxWidgets.git] / interface / wx / glcanvas.h

diff --git a/interface/wx/glcanvas.h b/interface/wx/glcanvas.h
index 3eefc74a3bfad116c1114351d2d0c68b0e6fd518..49a38c958e6fbf110b96c892e9e4885b2bd0f4f0 100644 (file)
--- a/interface/wx/glcanvas.h
+++ b/interface/wx/glcanvas.h
@@ -1,38 +1,40 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        glcanvas.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        glcanvas.h

-// Purpose:     interface of wxGLContext
+// Purpose:     interface of wxGLContext and wxGLCanvas

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxGLContext
 
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxGLContext
 

-    An instance of a wxGLContext represents the state of an OpenGL state machine
-    and the connection between OpenGL and the system.
+    An instance of a wxGLContext represents the state of an OpenGL state
+    machine and the connection between OpenGL and the system.

 
     The OpenGL state includes everything that can be set with the OpenGL API:
 
     The OpenGL state includes everything that can be set with the OpenGL API:

-    colors, rendering variables, display lists, texture objects, etc.
-    Although it is possible to have multiple rendering contexts share display lists
-    in order to save resources,
-    this method is hardly used today any more, because display lists are only a
-    tiny fraction of the overall state.
+    colors, rendering variables, display lists, texture objects, etc. Although
+    it is possible to have multiple rendering contexts share display lists in
+    order to save resources, this method is hardly used today any more, because
+    display lists are only a tiny fraction of the overall state.

 
     Therefore, one rendering context is usually used with or bound to multiple
 
     Therefore, one rendering context is usually used with or bound to multiple

-    output windows in turn,
-    so that the application has access to the complete and identical state while
-    rendering into each window.
+    output windows in turn, so that the application has access to the complete
+    and identical state while rendering into each window.

 
     Binding (making current) a rendering context with another instance of a
 
     Binding (making current) a rendering context with another instance of a

-    wxGLCanvas however works only
-    if the other wxGLCanvas was created with the same attributes as the wxGLCanvas
-    from which the wxGLContext
-    was initialized. (This applies to sharing display lists among contexts
+    wxGLCanvas however works only if the other wxGLCanvas was created with the
+    same attributes as the wxGLCanvas from which the wxGLContext was
+    initialized. (This applies to sharing display lists among contexts

     analogously.)
 
     analogously.)
 

-    Note that some wxGLContext features are extremely platform-specific - its best
-    to check your native platform's glcanvas header (on windows include/wx/msw/glcanvas.h) to see what features your native platform provides.
+    Note that some wxGLContext features are extremely platform-specific - its
+    best to check your native platform's glcanvas header (on windows
+    include/wx/msw/glcanvas.h) to see what features your native platform
+    provides.
+    
+    wxHAS_OPENGL_ES is defined on platforms that only have this implementation
+    available (eg the iPhone) und don't support the full specification.

 
     @library{wxgl}
     @category{gl}
 
     @library{wxgl}
     @category{gl}


@@ -46,40 +48,45 @@ public:
         Constructor.
 
         @param win
         Constructor.
 
         @param win

-            The canvas that is used to initialize this context. This parameter is
-        needed only temporarily,
-            and the caller may do anything with it (e.g. destroy the window) after the
-        constructor returned.
-            It will be possible to bind (make current) this context to any other
-        wxGLCanvas that has been created
-            with equivalent attributes as win.
+            The canvas that is used to initialize this context. This parameter
+            is needed only temporarily, and the caller may do anything with it
+            (e.g. destroy the window) after the constructor returned. @n
+            It will be possible to bind (make current) this context to any
+            other wxGLCanvas that has been created with equivalent attributes
+            as win.

         @param other
         @param other

-            Context to share display lists with or @NULL (the default) for no sharing.
+            Context to share display lists with or @NULL (the default) for no
+            sharing.

     */
     wxGLContext(wxGLCanvas* win, const wxGLContext* other = NULL);
 
     /**
     */
     wxGLContext(wxGLCanvas* win, const wxGLContext* other = NULL);
 
     /**

-        Makes the OpenGL state that is represented by this rendering context current
-        with the wxGLCanvas @e win.
-        Note that @a win can be a different wxGLCanvas window than the one that was
-        passed to the constructor of this rendering context.
-        If  @e RC  is an object of type wxGLContext, the statements @e
-        RC.SetCurrent(win); and @e win.SetCurrent(RC); are equivalent,
-        see wxGLCanvas::SetCurrent.
+        Makes the OpenGL state that is represented by this rendering context
+        current with the wxGLCanvas @e win.
+
+        @note @a win can be a different wxGLCanvas window than the one that was
+              passed to the constructor of this rendering context. If @e RC is
+              an object of type wxGLContext, the statements
+              @e "RC.SetCurrent(win);" and @e "win.SetCurrent(RC);" are
+              equivalent, see wxGLCanvas::SetCurrent().

     */
     virtual bool SetCurrent(const wxGLCanvas& win) const;
 };
 
 /**
     */
     virtual bool SetCurrent(const wxGLCanvas& win) const;
 };
 
 /**

+    @anchor wxGL_FLAGS
+

     Constants for use with wxGLCanvas.
 
     Constants for use with wxGLCanvas.
 

-    Notice that not all implementation support options such as stereo,
-    auxiliary buffers, alpha channel, and accumulator buffer, use
-    wxGLCanvas::IsDisplaySupported() to check for individual attributes support.
+    @note Not all implementations support options such as stereo, auxiliary
+          buffers, alpha channel, and accumulator buffer, use
+          wxGLCanvas::IsDisplaySupported() to check for individual attributes
+          support.

  */
 enum
 {
  */
 enum
 {

-    /// Use true color palette (on if no attributes at all specified).
+    /// Use true color (the default if no attributes at all are specified);
+    /// do not use a palette.

     WX_GL_RGBA = 1,
 
     /// Specifies the number of bits for buffer if not WX_GL_RGBA.
     WX_GL_RGBA = 1,
 
     /// Specifies the number of bits for buffer if not WX_GL_RGBA.


@@ -130,7 +137,7 @@ enum
     /// 1 for multisampling support (antialiasing)
     WX_GL_SAMPLE_BUFFERS,
 
     /// 1 for multisampling support (antialiasing)
     WX_GL_SAMPLE_BUFFERS,
 

-    /// 4 for 2x2 antialising supersampling on most graphics cards
+    /// 4 for 2x2 antialiasing supersampling on most graphics cards

     WX_GL_SAMPLES
 
 };
     WX_GL_SAMPLES
 
 };


@@ -139,36 +146,36 @@ enum
     @class wxGLCanvas
 
     wxGLCanvas is a class for displaying OpenGL graphics. It is always used in
     @class wxGLCanvas
 
     wxGLCanvas is a class for displaying OpenGL graphics. It is always used in

-    conjunction with wxGLContext as the context can only be
-    be made current (i.e. active for the OpenGL commands) when it is associated to
-    a wxGLCanvas.
-
-    More precisely, you first need to create a wxGLCanvas window and then create an
-    instance of a wxGLContext that is initialized with this
-    wxGLCanvas and then later use either wxGLCanvas::SetCurrent
-    with the instance of the wxGLContext or
-    wxGLContext::SetCurrent with the instance of
-    the wxGLCanvas (which might be not the same as was used
-    for the creation of the context) to bind the OpenGL state that is represented
-    by the rendering context to the canvas, and then finally call
-    wxGLCanvas::SwapBuffers to swap the buffers of
-    the OpenGL canvas and thus show your current output.
-
-    Notice that previous versions of wxWidgets used to implicitly create a
-    wxGLContext inside wxGLCanvas itself. This is still supported in the current
-    version but is deprecated now and will be removed in the future, please update
-    your code to create the rendering contexts explicitly.
-
-    To set up the attributes for the canvas (number of bits for the depth buffer,
-    number of bits for the stencil buffer and so on) you should set up the correct
-    values of
-    the @e attribList parameter. The values that should be set up and their
-    meanings will be described below.
-
-    Notice that OpenGL is not enabled by default. To switch it on, you need to edit
-    setup.h under Windows and set @c wxUSE_GLCANVAS to 1 (you may also need
-    to have to add @c opengl32.lib and @c glu32.lib to the list of libraries
-    your program is linked with). On Unix, pass @c --with-opengl to configure.
+    conjunction with wxGLContext as the context can only be made current (i.e.
+    active for the OpenGL commands) when it is associated to a wxGLCanvas.
+
+    More precisely, you first need to create a wxGLCanvas window and then
+    create an instance of a wxGLContext that is initialized with this
+    wxGLCanvas and then later use either SetCurrent() with the instance of the
+    wxGLContext or wxGLContext::SetCurrent() with the instance of the
+    wxGLCanvas (which might be not the same as was used for the creation of the
+    context) to bind the OpenGL state that is represented by the rendering
+    context to the canvas, and then finally call SwapBuffers() to swap the
+    buffers of the OpenGL canvas and thus show your current output.
+
+    Notice that versions of wxWidgets previous to 2.9 used to implicitly create a
+    wxGLContext inside wxGLCanvas itself. This is still supported in the
+    current version but is deprecated now and will be removed in the future,
+    please update your code to create the rendering contexts explicitly.
+
+    To set up the attributes for the canvas (number of bits for the depth
+    buffer, number of bits for the stencil buffer and so on) you should set up
+    the correct values of the @e attribList parameter. The values that should
+    be set up and their meanings will be described below.
+
+    @note
+        On those platforms which use a configure script (e.g. Linux and Mac OS)
+        OpenGL support is automatically enabled if the relative headers and
+        libraries are found.
+        To switch it on under the other platforms (e.g. Windows), you need to edit
+        the @c setup.h file and set @c wxUSE_GLCANVAS to @c 1 and then also pass
+        @c USE_OPENGL=1 to the make utility. You may also need to add @c opengl32.lib
+        and @c glu32.lib to the list of the libraries your program is linked with.

 
     @library{wxgl}
     @category{gl}
 
     @library{wxgl}
     @category{gl}


@@ -179,24 +186,24 @@ class wxGLCanvas : public wxWindow
 {
 public:
     /**
 {
 public:
     /**

-        Creates a window with the given parameters. Notice that you need to create and
-        use a wxGLContext to output to this window.
-        If
+        Creates a window with the given parameters. Notice that you need to
+        create and use a wxGLContext to output to this window.

 
 

-        @param attribList is not specified, double buffered RGBA mode is used.
+        If @a attribList is not specified, double buffered RGBA mode is used.

 
 

-        parent
+        @param parent

             Pointer to a parent window.
         @param id
             Window identifier. If -1, will automatically create an identifier.
         @param pos
             Window position. wxDefaultPosition is (-1, -1) which indicates that
             Pointer to a parent window.
         @param id
             Window identifier. If -1, will automatically create an identifier.
         @param pos
             Window position. wxDefaultPosition is (-1, -1) which indicates that

-        wxWidgets
-            should generate a default position for the window.
+            wxWidgets should generate a default position for the window.

         @param size
         @param size

-            Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets should
-            generate a default size for the window. If no suitable size can be found,
-        the window will be sized to 20x20 pixels so that the window is visible but obviously not correctly sized.
+            Window size. wxDefaultSize is (-1, -1) which indicates that
+            wxWidgets should generate a default size for the window. If no
+            suitable size can be found, the window will be sized to 20x20
+            pixels so that the window is visible but obviously not correctly
+            sized.

         @param style
             Window style.
         @param name
         @param style
             Window style.
         @param name


@@ -204,24 +211,24 @@ public:
         @param attribList
             Array of integers. With this parameter you can set the device
             context attributes associated to this window. This array is
         @param attribList
             Array of integers. With this parameter you can set the device
             context attributes associated to this window. This array is

-            zero-terminated: it should be set up with constants described in
-            the table above. If a constant should be followed by a value, put
-            it in the next array position. For example, the WX_GL_DEPTH_SIZE
-            should be followed by the value that indicates the number of bits
-            for the depth buffer, e.g:
+            zero-terminated: it should be set up using @ref wxGL_FLAGS
+            constants. If a constant should be followed by a value, put it in
+            the next array position. For example, WX_GL_DEPTH_SIZE should be
+            followed by the value that indicates the number of bits for the
+            depth buffer, e.g.:

             @code
             attribList[n++] = WX_GL_DEPTH_SIZE;
             attribList[n++] = 32;
             attribList[n] = 0; // terminate the list
             @endcode
             If the attribute list is not specified at all, i.e. if this
             @code
             attribList[n++] = WX_GL_DEPTH_SIZE;
             attribList[n++] = 32;
             attribList[n] = 0; // terminate the list
             @endcode
             If the attribute list is not specified at all, i.e. if this

-            parameter is @NULL, the default attributes including @c WX_GL_RGBA
-            and @c WX_GL_DOUBLEBUFFER are used. But notice that if you do
-            specify some attributes you also need to explicitly include these
-            two default attributes in the list if you need them.
+            parameter is @NULL, the default attributes including WX_GL_RGBA and
+            WX_GL_DOUBLEBUFFER are used. But notice that if you do specify some
+            attributes you also need to explicitly include these two default
+            attributes in the list if you need them.

         @param palette
         @param palette

-            Palette for indexed colour (i.e. non WX_GL_RGBA) mode.
-            Ignored under most platforms.
+            Palette for indexed colour (i.e. non WX_GL_RGBA) mode. Ignored
+            under most platforms.

     */
     wxGLCanvas(wxWindow* parent, wxWindowID id = wxID_ANY,
                const int* attribList = NULL,
     */
     wxGLCanvas(wxWindow* parent, wxWindowID id = wxID_ANY,
                const int* attribList = NULL,


@@ -233,37 +240,52 @@ public:
 
     /**
         Determines if a canvas having the specified attributes is available.
 
     /**
         Determines if a canvas having the specified attributes is available.

-        Returns @true if attributes are supported.

 
         @param attribList
 
         @param attribList

-            See attribList for wxGLCanvas().
+            See @a attribList for wxGLCanvas().
+
+        @return @true if attributes are supported.
+    */
+    static bool IsDisplaySupported(const int* attribList);
+
+    /**
+        Returns true if the extension with given name is supported
+
+        Notice that while this function is implemented for all of GLX, WGL and
+        AGL the extensions names are usually not the same for different
+        platforms and so the code using it still usually uses conditional
+        compilation.

     */
     */

-    static bool IsDisplaySupported(const int* attribList = NULL);
+    static bool IsExtensionSupported(const char *extension);

 
     /**
 
     /**

-        Sets the current colour for this window (using @c glcolor3f()), using the
-        wxWidgets colour database to find a named colour.
+        Sets the current colour for this window (using @c glcolor3f()), using
+        the wxWidgets colour database to find a named colour.

     */
     bool SetColour(const wxString& colour);
 
     /**
     */
     bool SetColour(const wxString& colour);
 
     /**

-        Makes the OpenGL state that is represented by the OpenGL rendering context
-        @a context current, i.e. it will be used by all subsequent OpenGL calls.
-        This is equivalent to wxGLContext::SetCurrent
-        called with this window as parameter.
-        Note that this function may only be called when the window is shown on screen,
-        in particular it can't usually be called from the constructor as the window
-        isn't yet shown at this moment.
-        Returns @false if an error occurred.
+        Makes the OpenGL state that is represented by the OpenGL rendering
+        context @a context current, i.e. it will be used by all subsequent
+        OpenGL calls.
+
+        This is equivalent to wxGLContext::SetCurrent() called with this window
+        as parameter.
+
+        @note This function may only be called when the window is shown on
+              screen, in particular it can't usually be called from the
+              constructor as the window isn't yet shown at this moment.
+
+        @return @false if an error occurred.

     */
     */

-    bool SetCurrent(const wxGLContext context);
+    bool SetCurrent(const wxGLContext& context) const;

 
     /**
 
     /**

-        Swaps the double-buffer of this window, making the back-buffer the front-buffer
-        and vice versa,
-        so that the output of the previous OpenGL commands is displayed on the window.
-        Returns @false if an error occurred.
+        Swaps the double-buffer of this window, making the back-buffer the
+        front-buffer and vice versa, so that the output of the previous OpenGL
+        commands is displayed on the window.
+
+        @return @false if an error occurred.

     */
     virtual bool SwapBuffers();
 };
     */
     virtual bool SwapBuffers();
 };

-