[wxWidgets.git] / docs / latex / wx / glcanvas.tex

\section{\class{wxGLCanvas}}\label{wxglcanvas}

wxGLCanvas is a class for displaying OpenGL graphics. There are
wrappers for OpenGL on Windows, and GTK+ and Motif.

To use this class, create a wxGLCanvas window, call \helpref{wxGLCanvas::SetCurrent}{wxglcanvassetcurrent} 
to direct normal OpenGL commands to the window, and then call \helpref{wxGLCanvas::SwapBuffers}{wxglcanvasswapbuffers} 
to show the OpenGL buffer on the window.

To set up the attributes for the rendering context (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 {\it attribList} parameter. The values that should be set up and their meanings will be described below.

To switch wxGLCanvas support on under Windows, edit setup.h and set
{\tt wxUSE\_GLCANVAS} to $1$. You may also need to have to add
{\tt opengl32.lib} to the list of libraries your program is linked with. On
Unix, pass {\tt --with-opengl} to configure to compile using OpenGL or Mesa.

\wxheading{Derived from}

\helpref{wxWindow}{wxwindow}\\
\helpref{wxEvtHandler}{wxevthandler}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/glcanvas.h>

\wxheading{Window styles}

There are no specific window styles for this class.

See also \helpref{window styles overview}{windowstyles}.

\wxheading{Constants}

The generic GL implementation doesn't support many of these options, such as stereo, auxiliary buffers,
alpha channel, and accum buffer. Other implementations may support them.

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\windowstyle{WX\_GL\_RGBA}}{Use true colour}
\twocolitem{\windowstyle{WX\_GL\_BUFFER\_SIZE}}{Bits for buffer if not WX\_GL\_RGBA}
\twocolitem{\windowstyle{WX\_GL\_LEVEL}}{0 for main buffer, >0 for overlay, <0 for underlay}
\twocolitem{\windowstyle{WX\_GL\_DOUBLEBUFFER}}{Use doublebuffer}
\twocolitem{\windowstyle{WX\_GL\_STEREO}}{Use stereoscopic display}
\twocolitem{\windowstyle{WX\_GL\_AUX\_BUFFERS}}{Number of auxiliary buffers (not all implementation support this option)}
\twocolitem{\windowstyle{WX\_GL\_MIN\_RED}}{Use red buffer with most bits (> MIN\_RED bits)}
\twocolitem{\windowstyle{WX\_GL\_MIN\_GREEN}}{Use green buffer with most bits (> MIN\_GREEN bits) }
\twocolitem{\windowstyle{WX\_GL\_MIN\_BLUE}}{Use blue buffer with most bits (> MIN\_BLUE bits) }
\twocolitem{\windowstyle{WX\_GL\_MIN\_ALPHA}}{Use alpha buffer with most bits (> MIN\_ALPHA bits)}
\twocolitem{\windowstyle{WX\_GL\_DEPTH\_SIZE}}{Bits for Z-buffer (0,16,32)}
\twocolitem{\windowstyle{WX\_GL\_STENCIL\_SIZE}}{Bits for stencil buffer}
\twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_RED}}{Use red accum buffer with most bits (> MIN\_ACCUM\_RED bits)}
\twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_GREEN}}{Use green buffer with most bits (> MIN\_ACCUM\_GREEN bits)}
\twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_BLUE}}{Use blue buffer with most bits (> MIN\_ACCUM\_BLUE bits)}
\twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_ALPHA}}{Use blue buffer with most bits (> MIN\_ACCUM\_ALPHA bits)}
\end{twocollist}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxGLCanvas::wxGLCanvas}\label{wxglcanvasconstr}

\func{void}{wxGLCanvas}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id = -1}, \param{const wxPoint\&}{ pos},
 \param{const wxSize\&}{ size}, \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
 \param{int*}{ attribList = 0}, \param{const wxPalette\&}{ palette = wxNullPalette}}

\func{void}{wxGLCanvas}{\param{wxWindow* }{parent}, \param{wxGLCanvas* }{ sharedCanvas = NULL}, \param{wxWindowID}{ id = -1}, \param{const wxPoint\&}{ pos},
 \param{const wxSize\&}{ size}, \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
 \param{int*}{ attribList = 0}, \param{const wxPalette\&}{ palette = wxNullPalette}}

\func{void}{wxGLCanvas}{\param{wxWindow* }{parent}, \param{wxGLContext* }{ sharedContext = NULL}, \param{wxWindowID}{ id = -1}, \param{const wxPoint\&}{ pos},
 \param{const wxSize\&}{ size}, \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
 \param{int*}{ attribList = 0}, \param{const wxPalette\&}{ palette = wxNullPalette}}

Constructor.

\docparam{parent}{Pointer to a parent window.}

\docparam{sharedcontext}{Context to share object resources with.}

\docparam{id}{Window identifier. If -1, will automatically create an identifier.}

\docparam{pos}{Window position. wxDefaultPosition is (-1, -1) which indicates that wxWidgets
should generate a default position for the window.}

\docparam{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.}

\docparam{style}{Window style.}

\docparam{name}{Window name.}

\docparam{attribList}{Array of int. 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, so:}

\begin{verbatim}
attribList[index]= WX_GL_DEPTH_SIZE;
attribList[index+1]=32;
and so on.
\end{verbatim}

\docparam{palette}{If the window has the palette, it should by pass this value.
Note: palette and WX\_GL\_RGBA are mutually exclusive.}

\membersection{wxGLCanvas::GetContext}\label{wxglcanvasgetcontext}

\func{wxGLContext*}{GetContext}{\void}

Obtains the context that is associated with this canvas.

\membersection{wxGLCanvas::SetCurrent}\label{wxglcanvassetcurrent}

\func{void}{SetCurrent}{\void}

Sets this canvas as the current recipient of OpenGL calls.
Each canvas contain an OpenGL device context that has been created during
the creation of this window. So this call sets the current device context
as the target device context for OpenGL operations.

\membersection{wxGLCanvas::SetColour}\label{wxglcanvassetcolour}

\func{void}{SetColour}{\param{const char*}{ colour}}

Sets the current colour for this window, using the wxWidgets colour database to find a named colour.

\membersection{wxGLCanvas::SwapBuffers}\label{wxglcanvasswapbuffers}

\func{void}{SwapBuffers}{\void}

Displays the previous OpenGL commands on the window.
Commit	Line	Data
8b089c5e JS	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	To use this class, create a wxGLCanvas window, call \helpref{wxGLCanvas::SetCurrent}{wxglcanvassetcurrent}
	7	to direct normal OpenGL commands to the window, and then call \helpref{wxGLCanvas::SwapBuffers}{wxglcanvasswapbuffers}
	8	to show the OpenGL buffer on the window.
	9
dd27a3bd JS	10	To set up the attributes for the rendering context (number of bits for the depth buffer,
	11	number of bits for the stencil buffer and so on) you should set up the correct values of
	12	the {\it attribList} parameter. The values that should be set up and their meanings will be described below.
	13
1162d0a2 VZ	14	To switch wxGLCanvas support on under Windows, edit setup.h and set
	15	{\tt wxUSE\_GLCANVAS} to $1$. You may also need to have to add
	16	{\tt opengl32.lib} to the list of libraries your program is linked with. On
	17	Unix, pass {\tt --with-opengl} to configure to compile using OpenGL or Mesa.
8b089c5e JS	18
	19	\wxheading{Derived from}
	20
8b089c5e JS	21	\helpref{wxWindow}{wxwindow}\\
	22	\helpref{wxEvtHandler}{wxevthandler}\\
	23	\helpref{wxObject}{wxobject}
	24
	25	\wxheading{Include files}
	26
	27	<wx/glcanvas.h>
	28
	29	\wxheading{Window styles}
	30
	31	There are no specific window styles for this class.
	32
	33	See also \helpref{window styles overview}{windowstyles}.
	34
dd27a3bd JS	35	\wxheading{Constants}
	36
	37	The generic GL implementation doesn't support many of these options, such as stereo, auxiliary buffers,
	38	alpha channel, and accum buffer. Other implementations may support them.
	39
	40	\twocolwidtha{5cm}
	41	\begin{twocollist}\itemsep=0pt
	42	\twocolitem{\windowstyle{WX\_GL\_RGBA}}{Use true colour}
	43	\twocolitem{\windowstyle{WX\_GL\_BUFFER\_SIZE}}{Bits for buffer if not WX\_GL\_RGBA}
	44	\twocolitem{\windowstyle{WX\_GL\_LEVEL}}{0 for main buffer, >0 for overlay, <0 for underlay}
	45	\twocolitem{\windowstyle{WX\_GL\_DOUBLEBUFFER}}{Use doublebuffer}
	46	\twocolitem{\windowstyle{WX\_GL\_STEREO}}{Use stereoscopic display}
	47	\twocolitem{\windowstyle{WX\_GL\_AUX\_BUFFERS}}{Number of auxiliary buffers (not all implementation support this option)}
	48	\twocolitem{\windowstyle{WX\_GL\_MIN\_RED}}{Use red buffer with most bits (> MIN\_RED bits)}
	49	\twocolitem{\windowstyle{WX\_GL\_MIN\_GREEN}}{Use green buffer with most bits (> MIN\_GREEN bits) }
	50	\twocolitem{\windowstyle{WX\_GL\_MIN\_BLUE}}{Use blue buffer with most bits (> MIN\_BLUE bits) }
	51	\twocolitem{\windowstyle{WX\_GL\_MIN\_ALPHA}}{Use alpha buffer with most bits (> MIN\_ALPHA bits)}
	52	\twocolitem{\windowstyle{WX\_GL\_DEPTH\_SIZE}}{Bits for Z-buffer (0,16,32)}
	53	\twocolitem{\windowstyle{WX\_GL\_STENCIL\_SIZE}}{Bits for stencil buffer}
	54	\twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_RED}}{Use red accum buffer with most bits (> MIN\_ACCUM\_RED bits)}
	55	\twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_GREEN}}{Use green buffer with most bits (> MIN\_ACCUM\_GREEN bits)}
	56	\twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_BLUE}}{Use blue buffer with most bits (> MIN\_ACCUM\_BLUE bits)}
	57	\twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_ALPHA}}{Use blue buffer with most bits (> MIN\_ACCUM\_ALPHA bits)}
	58	\end{twocollist}
	59
8b089c5e JS	60	\latexignore{\rtfignore{\wxheading{Members}}}
	61
	62	\membersection{wxGLCanvas::wxGLCanvas}\label{wxglcanvasconstr}
	63
	64	\func{void}{wxGLCanvas}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id = -1}, \param{const wxPoint\&}{ pos},
	65	\param{const wxSize\&}{ size}, \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
	66	\param{int*}{ attribList = 0}, \param{const wxPalette\&}{ palette = wxNullPalette}}
	67
	68	\func{void}{wxGLCanvas}{\param{wxWindow* }{parent}, \param{wxGLCanvas* }{ sharedCanvas = NULL}, \param{wxWindowID}{ id = -1}, \param{const wxPoint\&}{ pos},
	69	\param{const wxSize\&}{ size}, \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
	70	\param{int*}{ attribList = 0}, \param{const wxPalette\&}{ palette = wxNullPalette}}
	71
	72	\func{void}{wxGLCanvas}{\param{wxWindow* }{parent}, \param{wxGLContext* }{ sharedContext = NULL}, \param{wxWindowID}{ id = -1}, \param{const wxPoint\&}{ pos},
	73	\param{const wxSize\&}{ size}, \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
	74	\param{int*}{ attribList = 0}, \param{const wxPalette\&}{ palette = wxNullPalette}}
	75
	76	Constructor.
	77
dd27a3bd JS	78	\docparam{parent}{Pointer to a parent window.}
dd27a3bd JS	79
01168e95 RN	80	\docparam{sharedcontext}{Context to share object resources with.}
01168e95 RN	81
dd27a3bd JS	82	\docparam{id}{Window identifier. If -1, will automatically create an identifier.}
dd27a3bd JS	83
fc2171bd	84	\docparam{pos}{Window position. wxDefaultPosition is (-1, -1) which indicates that wxWidgets
dd27a3bd JS	85	should generate a default position for the window.}
dd27a3bd JS	86
fc2171bd	87	\docparam{size}{Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets should
dd27a3bd JS	88	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.}
	89
	90	\docparam{style}{Window style.}
	91
	92	\docparam{name}{Window name.}
	93
	94	\docparam{attribList}{Array of int. With this parameter you can set the device context attributes associated to this window.
	95	This array is zero-terminated: it should be set up with constants described in the table above.
	96	If a constant should be followed by a value, put it in the next array position.
	97	For example, the WX\_GL\_DEPTH\_SIZE should be followed by the value that indicates the number of
e119d049	98	bits for the depth buffer, so:}
dd27a3bd JS	99
	100	\begin{verbatim}
	101	attribList[index]= WX_GL_DEPTH_SIZE;
	102	attribList[index+1]=32;
	103	and so on.
	104	\end{verbatim}
dd27a3bd JS	105
	106	\docparam{palette}{If the window has the palette, it should by pass this value.
	107	Note: palette and WX\_GL\_RGBA are mutually exclusive.}
	108
01168e95 RN	109	\membersection{wxGLCanvas::GetContext}\label{wxglcanvasgetcontext}
	110
	111	\func{wxGLContext*}{GetContext}{\void}
	112
	113	Obtains the context that is associated with this canvas.
	114
8b089c5e JS	115	\membersection{wxGLCanvas::SetCurrent}\label{wxglcanvassetcurrent}
	116
	117	\func{void}{SetCurrent}{\void}
	118
	119	Sets this canvas as the current recipient of OpenGL calls.
dd27a3bd JS	120	Each canvas contain an OpenGL device context that has been created during
	121	the creation of this window. So this call sets the current device context
	122	as the target device context for OpenGL operations.
8b089c5e JS	123
	124	\membersection{wxGLCanvas::SetColour}\label{wxglcanvassetcolour}
	125
	126	\func{void}{SetColour}{\param{const char*}{ colour}}
	127
fc2171bd	128	Sets the current colour for this window, using the wxWidgets colour database to find a named colour.
8b089c5e JS	129
	130	\membersection{wxGLCanvas::SwapBuffers}\label{wxglcanvasswapbuffers}
	131
	132	\func{void}{SwapBuffers}{\void}
	133
	134	Displays the previous OpenGL commands on the window.
	135