Reviewed some g* interface headers.
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56606 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
// Name: glcanvas.h
|
||||
// Purpose: interface of wxGLContext
|
||||
// Purpose: interface of wxGLContext and wxGLCanvas
|
||||
// Author: wxWidgets team
|
||||
// RCS-ID: $Id$
|
||||
// Licence: wxWindows license
|
||||
@@ -9,30 +9,29 @@
|
||||
/**
|
||||
@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:
|
||||
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
|
||||
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
|
||||
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.)
|
||||
|
||||
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.
|
||||
|
||||
@library{wxgl}
|
||||
@category{gl}
|
||||
@@ -46,36 +45,40 @@ public:
|
||||
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
|
||||
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);
|
||||
|
||||
/**
|
||||
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;
|
||||
};
|
||||
|
||||
/**
|
||||
@anchor wxGL_FLAGS
|
||||
|
||||
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
|
||||
{
|
||||
@@ -139,36 +142,33 @@ enum
|
||||
@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.
|
||||
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 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.
|
||||
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 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.
|
||||
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.
|
||||
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.
|
||||
@note 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.
|
||||
|
||||
@library{wxgl}
|
||||
@category{gl}
|
||||
@@ -179,24 +179,24 @@ class wxGLCanvas : public wxWindow
|
||||
{
|
||||
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
|
||||
wxWidgets
|
||||
should generate a default position for the window.
|
||||
wxWidgets should generate a default position for the window.
|
||||
@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
|
||||
@@ -204,24 +204,24 @@ public:
|
||||
@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
|
||||
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
|
||||
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,
|
||||
@@ -233,37 +233,42 @@ public:
|
||||
|
||||
/**
|
||||
Determines if a canvas having the specified attributes is available.
|
||||
Returns @true if attributes are supported.
|
||||
|
||||
@param attribList
|
||||
See attribList for wxGLCanvas().
|
||||
See @a attribList for wxGLCanvas().
|
||||
|
||||
@return @true if attributes are supported.
|
||||
*/
|
||||
static bool IsDisplaySupported(const int* attribList = NULL);
|
||||
|
||||
/**
|
||||
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);
|
||||
|
||||
/**
|
||||
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);
|
||||
|
||||
/**
|
||||
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();
|
||||
};
|
||||
|
||||
|
Reference in New Issue
Block a user