don't use _T() inside wxGetTranslation() and related macros (wxTRANSLATE, _, ......

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

diff --git a/docs/latex/wx/glcanvas.tex b/docs/latex/wx/glcanvas.tex
index a2f1abad3dfe95e3a3daedc14149ce3cfa55a7f3..ba2a49e3cc2660d39dd56b2fa4419ee90cba1b15 100644 (file)
--- a/docs/latex/wx/glcanvas.tex
+++ b/docs/latex/wx/glcanvas.tex
@@ -1,20 +1,34 @@
 \section{\class{wxGLCanvas}}\label{wxglcanvas}
 
 \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,
+wxGLCanvas is a class for displaying OpenGL graphics. It is always used in
+conjunction with \helpref{wxGLContext}{wxglcontext} as the context can only be
+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 \helpref{wxGLContext}{wxglcontext} that is initialized with this
+wxGLCanvas and then later use either \helpref{wxGLCanvas::SetCurrent}{wxglcanvassetcurrent} 
+with the instance of the \helpref{wxGLContext}{wxglcontext} or 
+\helpref{wxGLContext::SetCurrent}{wxglcontextsetcurrent} with the instance of
+the \helpref{wxGLCanvas}{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 
+\helpref{wxGLCanvas::SwapBuffers}{wxglcanvasswapbuffers} 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.
+
+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 {\it attribList} parameter. The values that should be set up and their meanings will be described below.
 
 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.
+Notice that OpenGL is not enabled by default. To switch it on, you need to edit
+setup.h under Windows and set {\tt wxUSE\_GLCANVAS} to $1$ (you may also need
+to have to add {\tt opengl32.lib} and {\tt glu32.lib} to the list of libraries
+your program is linked with). On Unix, pass {\tt --with-opengl} to configure.

 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 


@@ -26,6 +40,10 @@ Unix, pass {\tt --with-opengl} to configure to compile using OpenGL or Mesa.
 
 <wx/glcanvas.h>
 
 
 <wx/glcanvas.h>
 

+\wxheading{Library}
+
+\helpref{wxGl}{librarieslist}
+

 \wxheading{Window styles}
 
 There are no specific window styles for this class.
 \wxheading{Window styles}
 
 There are no specific window styles for this class.


@@ -57,28 +75,28 @@ alpha channel, and accum buffer. Other implementations may support them.
 \twocolitem{\windowstyle{WX\_GL\_MIN\_ACCUM\_ALPHA}}{Use blue buffer with most bits (> MIN\_ACCUM\_ALPHA bits)}
 \end{twocollist}
 
 \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}

 
 

-\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}}
+\membersection{wxGLCanvas::wxGLCanvas}\label{wxglcanvasconstr}

 
 

-\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{wxWindowID}{ id = wxID\_ANY},
+ \param{const int*}{ attribList = NULL},
+ \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},
+ \param{long}{ style=0}, \param{const wxString\& }{name="GLCanvas"},
+ \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}}
+Creates a window with the given parameters. Notice that you need to create and
+use a \helpref{wxGLContext}{wxglcontext} to output to this window.

 
 

-Constructor.
+If \arg{attribList} is not specified, double buffered RGBA mode is used.

 
 \docparam{parent}{Pointer to a parent window.}
 
 
 \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
 \docparam{id}{Window identifier. If -1, will automatically create an identifier.}
 
 \docparam{pos}{Window position. wxDefaultPosition is (-1, -1) which indicates that wxWidgets


@@ -91,45 +109,49 @@ generate a default size for the window. If no suitable size can be found, the wi
 
 \docparam{name}{Window name.}
 
 
 \docparam{name}{Window name.}
 

-\docparam{attribList}{Array of int. With this parameter you can set the device context attributes associated to this window.
+\docparam{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, so:}
 
 \begin{verbatim}
 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;
+attribList[index] = WX_GL_DEPTH_SIZE;
+attribList[index+1] = 32;

 and so on.
 \end{verbatim}
 
 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.}
+\docparam{palette}{Palette for indexed colour (i.e. non WX\_GL\_RGBA) mode.
+Ignored under most platforms.}
+

 
 

-\membersection{wxGLCanvas::GetContext}\label{wxglcanvasgetcontext}
+\membersection{wxGLCanvas::SetCurrent}\label{wxglcanvassetcurrent}

 
 

-\func{wxGLContext*}{GetContext}{\void}
+\func{void}{SetCurrent}{ \param{const wxGLContext&}{ context} }

 
 

-Obtains the context that is associated with this canvas.
+Makes the OpenGL state that is represented by the OpenGL rendering context
+\arg{context} current, i.e. it will be used by all subsequent OpenGL calls.

 
 

-\membersection{wxGLCanvas::SetCurrent}\label{wxglcanvassetcurrent}
+This is equivalent to \helpref{wxGLContext::SetCurrent}{wxglcontextsetcurrent} 
+called with this window as parameter.

 
 

-\func{void}{SetCurrent}{\void}
+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.

 
 

-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}
 
 
 \membersection{wxGLCanvas::SetColour}\label{wxglcanvassetcolour}
 

-\func{void}{SetColour}{\param{const char*}{ colour}}
+\func{void}{SetColour}{\param{const wxString\&}{ colour}}
+
+Sets the current colour for this window (using \texttt{glcolor3f()}), using the
+wxWidgets 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}
 
 \func{void}{SwapBuffers}{\void}
 
 
 \membersection{wxGLCanvas::SwapBuffers}\label{wxglcanvasswapbuffers}
 
 \func{void}{SwapBuffers}{\void}
 

-Displays the previous OpenGL commands on the window.
+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.