docs/latex/wx/glcanvas.tex

   1 \section{\class{wxGLCanvas}}\label{wxglcanvas}
   2
   3 wxGLCanvas is a class for displaying OpenGL graphics. It is always used in
   4 conjunction with \helpref{wxGLContext}{wxglcontext} as the context can only be
   5 be made current (i.e. active for the OpenGL commands) when it is associated to
   6 a wxGLCanvas.
   7
   8 More precisely, you first need to create a wxGLCanvas window and then create an
   9 instance of a \helpref{wxGLContext}{wxglcontext} that is initialized with this
  10 wxGLCanvas and then later use either \helpref{wxGLCanvas::SetCurrent}{wxglcanvassetcurrent}
  11 with the instance of the \helpref{wxGLContext}{wxglcontext} or
  12 \helpref{wxGLContext::SetCurrent}{wxglcontextsetcurrent} with the instance of
  13 the \helpref{wxGLCanvas}{wxglcanvas} (which might be not the same as was used
  14 for the creation of the context) to bind the OpenGL state that is represented
  15 by the rendering context to the canvas, and then finally call
  16 \helpref{wxGLCanvas::SwapBuffers}{wxglcanvasswapbuffers} to swap the buffers of
  17 the OpenGL canvas and thus show your current output.
  18
  19 Notice that previous versions of wxWidgets used to implicitly create a
  20 wxGLContext inside wxGLCanvas itself. This is still supported in the current
  21 version but is deprecated now and will be removed in the future, please update
  22 your code to create the rendering contexts explicitly.
  23
  24 To set up the attributes for the canvas (number of bits for the depth buffer,
  25 number of bits for the stencil buffer and so on) you should set up the correct values of
  26 the {\it attribList} parameter. The values that should be set up and their meanings will be described below.
  27
  28 Notice that OpenGL is not enabled by default. To switch it on, you need to edit
  29 setup.h under Windows and set {\tt wxUSE\_GLCANVAS} to $1$ (you may also need
  30 to have to add {\tt opengl32.lib} and {\tt glu32.lib} to the list of libraries
  31 your program is linked with). On Unix, pass {\tt --with-opengl} to configure.
  32
  33 \wxheading{Derived from}
  34
  35 \helpref{wxWindow}{wxwindow}\\
  36 \helpref{wxEvtHandler}{wxevthandler}\\
  37 \helpref{wxObject}{wxobject}
  38
  39 \wxheading{Include files}
  40
  41 <wx/glcanvas.h>
  42
  43 \wxheading{Library}
  44
  45 \helpref{wxGl}{librarieslist}
  46
  47 \wxheading{Window styles}
  48
  49 There are no specific window styles for this class.
  50
  51 See also \helpref{window styles overview}{windowstyles}.
  52
  53 \wxheading{Constants}
  54
  55 The generic GL implementation doesn't support many of these options, such as stereo, auxiliary buffers,
  56 alpha channel, and accum buffer. Other implementations may support them.
  57
  58 \twocolwidtha{5cm}
  59 \begin{twocollist}\itemsep=0pt
  60 \twocolitem{\windowstyle{WX\_GL\_RGBA}}{Use true colour}
  61 \twocolitem{\windowstyle{WX\_GL\_BUFFER\_SIZE}}{Bits for buffer if not WX\_GL\_RGBA}
  62 \twocolitem{\windowstyle{WX\_GL\_LEVEL}}{0 for main buffer, >0 for overlay, <0 for underlay}
  63 \twocolitem{\windowstyle{WX\_GL\_DOUBLEBUFFER}}{Use doublebuffer}
  64 \twocolitem{\windowstyle{WX\_GL\_STEREO}}{Use stereoscopic display}
  65 \twocolitem{\windowstyle{WX\_GL\_AUX\_BUFFERS}}{Number of auxiliary buffers (not all implementations support this option)}
  66 \twocolitem{\windowstyle{WX\_GL\_MIN\_RED}}{Use red buffer with most bits (> MIN\_RED bits)}
  67 \twocolitem{\windowstyle{WX\_GL\_MIN\_GREEN}}{Use green buffer with most bits (> MIN\_GREEN bits) }
  68 \twocolitem{\windowstyle{WX\_GL\_MIN\_BLUE}}{Use blue buffer with most bits (> MIN\_BLUE bits) }
  69 \twocolitem{\windowstyle{WX\_GL\_MIN\_ALPHA}}{Use alpha buffer with most bits (> MIN\_ALPHA bits)}
  70 \twocolitem{\windowstyle{WX\_GL\_DEPTH\_SIZE}}{Bits for Z-buffer (0,16,32)}
  71 \twocolitem{\windowstyle{WX\_GL\_STENCIL\_SIZE}}{Bits for stencil buffer}
  72 \twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_RED}}{Use red accum buffer with most bits (> MIN\_ACCUM\_RED bits)}
  73 \twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_GREEN}}{Use green buffer with most bits (> MIN\_ACCUM\_GREEN bits)}
  74 \twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_BLUE}}{Use blue buffer with most bits (> MIN\_ACCUM\_BLUE bits)}
  75 \twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_ALPHA}}{Use blue buffer with most bits (> MIN\_ACCUM\_ALPHA bits)}
  76 \end{twocollist}
  77
  78 \wxheading{See also}
  79
  80 \helpref{wxGLContext}{wxglcontext}
  81
  82 \latexignore{\rtfignore{\wxheading{Members}}}
  83
  84
  85 \membersection{wxGLCanvas::wxGLCanvas}\label{wxglcanvasconstr}
  86
  87 \func{void}{wxGLCanvas}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id = wxID\_ANY},
  88  \param{const int*}{ attribList = NULL},
  89  \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},
  90  \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
  91  \param{const wxPalette\&}{ palette = wxNullPalette}}
  92
  93 Creates a window with the given parameters. Notice that you need to create and
  94 use a \helpref{wxGLContext}{wxglcontext} to output to this window.
  95
  96 If \arg{attribList} is not specified, double buffered RGBA mode is used.
  97
  98 \docparam{parent}{Pointer to a parent window.}
  99
 100 \docparam{id}{Window identifier. If -1, will automatically create an identifier.}
 101
 102 \docparam{pos}{Window position. wxDefaultPosition is (-1, -1) which indicates that wxWidgets
 103 should generate a default position for the window.}
 104
 105 \docparam{size}{Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets should
 106 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.}
 107
 108 \docparam{style}{Window style.}
 109
 110 \docparam{name}{Window name.}
 111
 112 \docparam{attribList}{Array of integers. With this parameter you can set the device context attributes associated to this window.
 113 This array is zero-terminated: it should be set up with constants described in the table above.
 114 If a constant should be followed by a value, put it in the next array position.
 115 For example, the WX\_GL\_DEPTH\_SIZE should be followed by the value that indicates the number of
 116 bits for the depth buffer, so:}
 117
 118 \begin{verbatim}
 119 attribList[index] = WX_GL_DEPTH_SIZE;
 120 attribList[index+1] = 32;
 121 and so on.
 122 \end{verbatim}
 123
 124 \docparam{palette}{Palette for indexed colour (i.e. non WX\_GL\_RGBA) mode.
 125 Ignored under most platforms.}
 126
 127
 128 \membersection{wxGLCanvas::SetCurrent}\label{wxglcanvassetcurrent}
 129
 130 \func{bool}{SetCurrent}{ \param{const wxGLContext&}{ context} }
 131
 132 Makes the OpenGL state that is represented by the OpenGL rendering context
 133 \arg{context} current, i.e. it will be used by all subsequent OpenGL calls.
 134
 135 This is equivalent to \helpref{wxGLContext::SetCurrent}{wxglcontextsetcurrent}
 136 called with this window as parameter.
 137
 138 Note that this function may only be called when the window is shown on screen,
 139 in particular it can't usually be called from the constructor as the window
 140 isn't yet shown at this moment.
 141
 142 Returns \false if an error occurred.
 143
 144
 145 \membersection{wxGLCanvas::SetColour}\label{wxglcanvassetcolour}
 146
 147 \func{void}{SetColour}{\param{const wxString\&}{ colour}}
 148
 149 Sets the current colour for this window (using \texttt{glcolor3f()}), using the
 150 wxWidgets colour database to find a named colour.
 151
 152
 153 \membersection{wxGLCanvas::SwapBuffers}\label{wxglcanvasswapbuffers}
 154
 155 \func{bool}{SwapBuffers}{\void}
 156
 157 Swaps the double-buffer of this window, making the back-buffer the front-buffer and vice versa,
 158 so that the output of the previous OpenGL commands is displayed on the window.
 159
 160 Returns \false if an error occurred.
 161