docs/latex/wx/glcanvas.tex

   1 \section{\class{wxGLCanvas}}\label{wxglcanvas}
   2
   3 wxGLCanvas is a class for displaying OpenGL graphics. There are
   4 wrappers for OpenGL on Windows, and GTK+ and Motif.
   5
   6 There are two ways to use this class:
   7
   8 For the older (before wx 2.7.x) and simpler method, create a wxGLCanvas window using one of the three
   9 constructors that implicitly create a rendering context, call \helpref{wxGLCanvas::SetCurrent}{wxglcanvassetcurrent}
  10 to direct normal OpenGL commands to the window, and then call \helpref{wxGLCanvas::SwapBuffers}{wxglcanvasswapbuffers}
  11 to show the OpenGL buffer on the window.
  12
  13 For the newer (wx 2.7.x+) method, create a wxGLCanvas window using the constructor that does \emph{not} create an implicit rendering context,
  14 create an explicit instance of a \helpref{wxGLContext}{wxglcontext} that is initialized with the wxGLCanvas yourself,
  15 then use either \helpref{wxGLCanvas::SetCurrent}{wxglcanvassetcurrentrc} with the instance of the \helpref{wxGLContext}{wxglcontext}
  16 or \helpref{wxGLContext::SetCurrent}{wxglcontextsetcurrent} with the instance of the \helpref{wxGLCanvas}{wxglcanvas}
  17 to bind the OpenGL state that is represented by the rendering context to the canvas, and then call
  18 \helpref{wxGLCanvas::SwapBuffers}{wxglcanvasswapbuffers} to swap the buffers of the OpenGL canvas and thus show your current output.
  19
  20 To set up the attributes for the canvas (number of bits for the depth buffer,
  21 number of bits for the stencil buffer and so on) you should set up the correct values of
  22 the {\it attribList} parameter. The values that should be set up and their meanings will be described below.
  23
  24 To switch on wxGLCanvas support on under Windows, edit setup.h and set
  25 {\tt wxUSE\_GLCANVAS} to $1$. You may also need to have to add
  26 {\tt opengl32.lib} to the list of libraries your program is linked with. On
  27 Unix, pass {\tt --with-opengl} to configure to compile using OpenGL or Mesa.
  28
  29 \wxheading{Derived from}
  30
  31 \helpref{wxWindow}{wxwindow}\\
  32 \helpref{wxEvtHandler}{wxevthandler}\\
  33 \helpref{wxObject}{wxobject}
  34
  35 \wxheading{Include files}
  36
  37 <wx/glcanvas.h>
  38
  39 \wxheading{Window styles}
  40
  41 There are no specific window styles for this class.
  42
  43 See also \helpref{window styles overview}{windowstyles}.
  44
  45 \wxheading{Constants}
  46
  47 The generic GL implementation doesn't support many of these options, such as stereo, auxiliary buffers,
  48 alpha channel, and accum buffer. Other implementations may support them.
  49
  50 \twocolwidtha{5cm}
  51 \begin{twocollist}\itemsep=0pt
  52 \twocolitem{\windowstyle{WX\_GL\_RGBA}}{Use true colour}
  53 \twocolitem{\windowstyle{WX\_GL\_BUFFER\_SIZE}}{Bits for buffer if not WX\_GL\_RGBA}
  54 \twocolitem{\windowstyle{WX\_GL\_LEVEL}}{0 for main buffer, >0 for overlay, <0 for underlay}
  55 \twocolitem{\windowstyle{WX\_GL\_DOUBLEBUFFER}}{Use doublebuffer}
  56 \twocolitem{\windowstyle{WX\_GL\_STEREO}}{Use stereoscopic display}
  57 \twocolitem{\windowstyle{WX\_GL\_AUX\_BUFFERS}}{Number of auxiliary buffers (not all implementation support this option)}
  58 \twocolitem{\windowstyle{WX\_GL\_MIN\_RED}}{Use red buffer with most bits (> MIN\_RED bits)}
  59 \twocolitem{\windowstyle{WX\_GL\_MIN\_GREEN}}{Use green buffer with most bits (> MIN\_GREEN bits) }
  60 \twocolitem{\windowstyle{WX\_GL\_MIN\_BLUE}}{Use blue buffer with most bits (> MIN\_BLUE bits) }
  61 \twocolitem{\windowstyle{WX\_GL\_MIN\_ALPHA}}{Use alpha buffer with most bits (> MIN\_ALPHA bits)}
  62 \twocolitem{\windowstyle{WX\_GL\_DEPTH\_SIZE}}{Bits for Z-buffer (0,16,32)}
  63 \twocolitem{\windowstyle{WX\_GL\_STENCIL\_SIZE}}{Bits for stencil buffer}
  64 \twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_RED}}{Use red accum buffer with most bits (> MIN\_ACCUM\_RED bits)}
  65 \twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_GREEN}}{Use green buffer with most bits (> MIN\_ACCUM\_GREEN bits)}
  66 \twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_BLUE}}{Use blue buffer with most bits (> MIN\_ACCUM\_BLUE bits)}
  67 \twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_ALPHA}}{Use blue buffer with most bits (> MIN\_ACCUM\_ALPHA bits)}
  68 \end{twocollist}
  69
  70 \wxheading{See also}
  71
  72 \helpref{wxGLContext}{wxglcontext}
  73
  74 \latexignore{\rtfignore{\wxheading{Members}}}
  75
  76
  77 \membersection{wxGLCanvas::wxGLCanvas}\label{wxglcanvasconstr}
  78
  79 \func{void}{wxGLCanvas}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id = -1},
  80  \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},
  81  \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
  82  \param{int*}{ attribList = 0}, \param{const wxPalette\&}{ palette = wxNullPalette}}
  83
  84 \func{void}{wxGLCanvas}{\param{wxWindow* }{parent}, \param{wxGLContext* }{sharedContext}, \param{wxWindowID}{ id = -1},
  85  \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},
  86  \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
  87  \param{int*}{ attribList = 0}, \param{const wxPalette\&}{ palette = wxNullPalette}}
  88
  89 \func{void}{wxGLCanvas}{\param{wxWindow* }{parent}, \param{wxGLCanvas* }{sharedCanvas}, \param{wxWindowID}{ id = -1},
  90  \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},
  91  \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
  92  \param{int*}{ attribList = 0}, \param{const wxPalette\&}{ palette = wxNullPalette}}
  93
  94 \func{void}{wxGLCanvas}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id = wxID\_ANY},
  95  \param{int*}{ attribList = 0},
  96  \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},
  97  \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
  98  \param{const wxPalette\&}{ palette = wxNullPalette}}
  99
 100 Constructors.
 101 The first three constructors implicitly create an instance of \helpref{wxGLContext}{wxglcontext}.
 102 The fourth constructur is identical to the first, except for the fact that it does \emph{not}
 103 create such an implicit rendering context, which means that you have to create an explicit instance
 104 of \helpref{wxGLContext}{wxglcontext} yourself (highly recommended for future compatibility with wxWidgets
 105 and the flexibility of your own program!).
 106
 107 Note that if you used one of the first three constructors, \helpref{wxGLCanvas::GetContext}{wxglcanvasgetcontext}
 108 returns the pointer to the implicitly created instance, and the \helpref{wxGLCanvas::SetCurrent}{wxglcanvassetcurrent}
 109 method \emph{without} the parameter should be used.
 110 If however you used the fourth constructor, \helpref{wxGLCanvas::GetContext}{wxglcanvasgetcontext} always returns NULL
 111 and the \helpref{wxGLCanvas::SetCurrent}{wxglcanvassetcurrentrc} method \emph{with} the parameter must be used!
 112
 113 \docparam{parent}{Pointer to a parent window.}
 114
 115 \docparam{sharedContext}{Context to share object resources with.}
 116
 117 %TODO document sharedCanvas meaning
 118
 119 \docparam{id}{Window identifier. If -1, will automatically create an identifier.}
 120
 121 \docparam{pos}{Window position. wxDefaultPosition is (-1, -1) which indicates that wxWidgets
 122 should generate a default position for the window.}
 123
 124 \docparam{size}{Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets should
 125 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.}
 126
 127 \docparam{style}{Window style.}
 128
 129 \docparam{name}{Window name.}
 130
 131 \docparam{attribList}{Array of int. With this parameter you can set the device context attributes associated to this window.
 132 This array is zero-terminated: it should be set up with constants described in the table above.
 133 If a constant should be followed by a value, put it in the next array position.
 134 For example, the WX\_GL\_DEPTH\_SIZE should be followed by the value that indicates the number of
 135 bits for the depth buffer, so:}
 136
 137 \begin{verbatim}
 138 attribList[index]= WX_GL_DEPTH_SIZE;
 139 attribList[index+1]=32;
 140 and so on.
 141 \end{verbatim}
 142
 143 \docparam{palette}{If the window has the palette, it should by pass this value.
 144 Note: palette and WX\_GL\_RGBA are mutually exclusive.}
 145
 146
 147 \membersection{wxGLCanvas::GetContext}\label{wxglcanvasgetcontext}
 148
 149 \func{wxGLContext*}{GetContext}{\void}
 150
 151 Obtains the context that is associated with this canvas if one was implicitly created (by use of one of the first three constructors).
 152 Always returns NULL if the canvas was constructed with the fourth constructor.
 153
 154
 155 \membersection{wxGLCanvas::SetCurrent}\label{wxglcanvassetcurrent}
 156
 157 \func{void}{SetCurrent}{\void}
 158
 159 If this canvas was created with one of the first three constructors,
 160 a call to this method makes the implicit rendering context of this canvas current with this canvas,
 161 so that subsequent OpenGL calls modify the OpenGL state of the implicit rendering context.
 162
 163 If this canvas was created with the fourth constructor, this method should not be called
 164 (use the SetCurrent method below with the parameter instead)!
 165
 166 Note that this function may only be called \emph{after} the window has been shown.
 167
 168
 169 \membersection{wxGLCanvas::SetCurrent}\label{wxglcanvassetcurrentrc}
 170
 171 \func{void}{SetCurrent}{ \param{const wxGLContext&}{ RC} }
 172
 173 If this canvas was created with one of the first three constructors,
 174 this method should not be called (use the SetCurrent above without the parameter instead)!
 175
 176 If this canvas was created with the fourth constructor, a call to this method
 177 makes the OpenGL state that is represented by the OpenGL rendering context { \it RC } current with this canvas,
 178 and if { \it win } is an object of type wxGLCanvas, the statements { \it win.SetCurrent(RC); } and { \it RC.SetCurrent(win); } are equivalent,
 179 see \helpref{wxGLContext::SetCurrent}{wxglcontextsetcurrent}.
 180
 181 Note that this function may only be called \emph{after} the window has been shown.
 182
 183
 184 \membersection{wxGLCanvas::SetColour}\label{wxglcanvassetcolour}
 185
 186 \func{void}{SetColour}{\param{const char*}{ colour}}
 187
 188 Sets the current colour for this window, using the wxWidgets colour database to find a named colour.
 189
 190
 191 \membersection{wxGLCanvas::SwapBuffers}\label{wxglcanvasswapbuffers}
 192
 193 \func{void}{SwapBuffers}{\void}
 194
 195 Swaps the double-buffer of this window, making the back-buffer the front-buffer and vice versa,
 196 so that the output of the previous OpenGL commands is displayed on the window.
 197