]> git.saurik.com Git - wxWidgets.git/blobdiff - docs/latex/wx/glcanvas.tex
add @DATE@, @TIME@ and @TITLE@ macros to HTML printing (extended/modified patch 1528679)
[wxWidgets.git] / docs / latex / wx / glcanvas.tex
index fddb1541eed2ba7b64a25fe6118d5e23375e72fe..af29c1f49ec667514d98cd5a13316b0a9be6028e 100644 (file)
@@ -7,14 +7,17 @@ To use this class, create a wxGLCanvas window, call \helpref{wxGLCanvas::SetCurr
 to direct normal OpenGL commands to the window, and then call \helpref{wxGLCanvas::SwapBuffers}{wxglcanvasswapbuffers} 
 to show the OpenGL buffer on the window.
 
 to direct normal OpenGL commands to the window, and then call \helpref{wxGLCanvas::SwapBuffers}{wxglcanvasswapbuffers} 
 to show the OpenGL buffer on the window.
 
-Please note that despite deriving from wxScrolledWindow, scrolling is not enabled for this class under
-Windows.
+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 wxUSE\_GLCANVAS to 1.
+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}
 
 
 \wxheading{Derived from}
 
-\helpref{wxScrolledWindow}{wxscrolledwindow}\\
 \helpref{wxWindow}{wxwindow}\\
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 \helpref{wxWindow}{wxwindow}\\
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
@@ -29,35 +32,116 @@ There are no specific window styles for this class.
 
 See also \helpref{window styles overview}{windowstyles}.
 
 
 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}
+
+\wxheading{See also}
+
+\helpref{wxGLContext}{wxglcontext}
+
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
+
 \membersection{wxGLCanvas::wxGLCanvas}\label{wxglcanvasconstr}
 
 \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"},
+\func{void}{wxGLCanvas}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id = -1},
+ \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},
+ \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
  \param{int*}{ attribList = 0}, \param{const wxPalette\&}{ palette = wxNullPalette}}
 
  \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"},
+\func{void}{wxGLCanvas}{\param{wxWindow* }{parent}, \param{wxGLContext* }{sharedContext}, \param{wxWindowID}{ id = -1},
+ \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},
+ \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
  \param{int*}{ attribList = 0}, \param{const wxPalette\&}{ palette = wxNullPalette}}
 
  \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"},
+\func{void}{wxGLCanvas}{\param{wxWindow* }{parent}, \param{wxGLCanvas* }{sharedCanvas}, \param{wxWindowID}{ id = -1},
+ \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},
+ \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
  \param{int*}{ attribList = 0}, \param{const wxPalette\&}{ palette = wxNullPalette}}
 
 Constructor.
 
  \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.}
+
+%TODO document sharedCanvas meaning
+
+\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.
 \membersection{wxGLCanvas::SetCurrent}\label{wxglcanvassetcurrent}
 
 \func{void}{SetCurrent}{\void}
 
 Sets this canvas as the current recipient of OpenGL calls.
+Each canvas contains 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.
+
+Note that this function may only be called after the window has been shown.
+
 
 \membersection{wxGLCanvas::SetColour}\label{wxglcanvassetcolour}
 
 \func{void}{SetColour}{\param{const char*}{ colour}}
 
 
 \membersection{wxGLCanvas::SetColour}\label{wxglcanvassetcolour}
 
 \func{void}{SetColour}{\param{const char*}{ colour}}
 
-Sets the current colour for this window, using the wxWindows colour database to find a named colour.
+Sets the current colour for this window, using the wxWidgets colour database to find a named colour.
+
 
 \membersection{wxGLCanvas::SwapBuffers}\label{wxglcanvasswapbuffers}
 
 
 \membersection{wxGLCanvas::SwapBuffers}\label{wxglcanvasswapbuffers}