b28dd88994
Combined patch with the following changes: - Don't add wxGLAttributes::Defaults() when the attributes-list is NULL. - Add display default attributes used in wx versions before 3.1 when the attributes-list is NULL. These attributes are different for each platform. - Fix wxMSW PixelFormatDescriptor initialization. - Don't set color buffers when RGBA() is used. - Fix setting colour sizes in OS X and a few other fixes. - Make documentation more clear about these subjects. Closes #17425.
919 lines
30 KiB
Objective-C
919 lines
30 KiB
Objective-C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: glcanvas.h
|
|
// Purpose: interface of wxGLContext and wxGLCanvas
|
|
// Author: wxWidgets team
|
|
// Licence: wxWindows licence
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
@class wxGLAttribsBase
|
|
|
|
This is the base class for wxGLAttributes and wxGLContextAttrs.
|
|
It stores internally the list required by OS and OpenGL driver for setting
|
|
display and rendering context attributes.
|
|
|
|
Normally this class is not used directly. But there's a case where it its
|
|
member functions are useful: setting attributes not handled by wxWidgets.
|
|
Suppose the OpenGL Board sets a new functionality of the context, by adding
|
|
a new attribute (let's call it NEW_CTX_F) and also a new type of context by
|
|
allowing a new bit value (let's call it NEW_BITS) for the CONTEXT_PROFILE_MASK_ARB
|
|
value. These new values can be added to the list using code like this:
|
|
|
|
@code
|
|
wxGLContextAttrs cxtAttrs;
|
|
// Some values
|
|
cxtAttrs.CoreProfile().OGLVersion(5, 0); // OGL 5.0, whenever available
|
|
cxtAttrs.PlatformDefaults();
|
|
// Values usually are platform-dependant named (even value assigned!)
|
|
#if defined(__WXMSW__)
|
|
cxtAttrs.AddAttribute(WGL_NEW_CTX_F);
|
|
cxtAttrs.AddAttribBits(WGL_CONTEXT_PROFILE_MASK_ARB, WGL_NEW_BITS);
|
|
#elif defined(__WXX11__)
|
|
cxtAttrs.AddAttribute(GLX_NEW_CTX_F);
|
|
cxtAttrs.AddAttribBits(GLX_CONTEXT_PROFILE_MASK_ARB, GLX_NEW_BITS);
|
|
#else
|
|
// Other platforms
|
|
#endif
|
|
cxtAttrs.EndList(); // Don't forget this
|
|
cxtAttrs.SetNeedsARB(true); // Context attributes are set by an ARB-function
|
|
@endcode
|
|
|
|
@since 3.1.0
|
|
|
|
@library{wxgl}
|
|
@category{gl}
|
|
|
|
@see wxGLCanvas, wxGLContext, wxGLContextAttrs, wxGLAttributes
|
|
*/
|
|
class WXDLLIMPEXP_GL wxGLAttribsBase
|
|
{
|
|
public:
|
|
/// Constructor.
|
|
wxGLAttribsBase();
|
|
|
|
/**
|
|
Adds an integer value to the list of attributes.
|
|
|
|
@param attribute
|
|
The value to add.
|
|
*/
|
|
void AddAttribute(int attribute);
|
|
|
|
/**
|
|
Combine (bitwise OR) a given value with the existing one, if any.
|
|
This function first searches for an identifier and then combines the
|
|
given value with the value right after the identifier.
|
|
If the identifier is not found, two new values (i.e. the identifier and
|
|
the given value) are added to the list.
|
|
|
|
@param searchVal
|
|
The identifier to search for.
|
|
@param combineVal
|
|
The value to combine with the existing one.
|
|
*/
|
|
void AddAttribBits(int searchVal, int combineVal);
|
|
|
|
/**
|
|
Sets the necessity of using special ARB-functions
|
|
(e.g. wglCreateContextAttribsARB in MSW) for some of the attributes of
|
|
the list.
|
|
Multi-sampling and modern context require these ARB-functions.
|
|
|
|
@param needsARB
|
|
@true if an ARB-function is needed for any of the attributes.
|
|
|
|
@see NeedsARB
|
|
*/
|
|
void SetNeedsARB(bool needsARB = true);
|
|
|
|
/// Delete contents and sets ARB-flag to false.
|
|
void Reset();
|
|
|
|
/**
|
|
Returns a pointer to the internal list of attributes. It's very unlikely
|
|
you need this function.
|
|
If the list is empty the returned value is @NULL.
|
|
*/
|
|
const int* GetGLAttrs() const;
|
|
|
|
/** Returns the size of the internal list of attributes.
|
|
Remember that the last value in the list must be a '0' (zero). So, a
|
|
minimal list is of size = 2, the first value is meaningful and the last is '0'.
|
|
*/
|
|
int GetSize();
|
|
|
|
/**
|
|
Returns the current value of the ARB-flag.
|
|
|
|
@see SetNeedsARB
|
|
*/
|
|
bool NeedsARB() const;
|
|
};
|
|
|
|
/**
|
|
@class wxGLAttributes
|
|
|
|
This class is used for setting display attributes when drawing through
|
|
OpenGL ("Pixel format" in MSW and OSX parlance, "Configs" in X11).
|
|
While framebuffer depth and samplers are still common, attributes
|
|
like layers overlay or not using true colour are rarely used nowadays.
|
|
|
|
Attributes can be chained. For example:
|
|
@code
|
|
wxGLAttributes dispAttrs;
|
|
dispAttrs.PlatformDefaults().MinRGBA(8, 8, 8, 8).DoubleBuffer().Depth(32).EndList();
|
|
@endcode
|
|
|
|
Notice that EndList() must be used as the last attribute. Not adding it will
|
|
likely result in nothing displayed at all.
|
|
|
|
@note Not all of platform-dependant available attributes are implemented in
|
|
wxWidgets. You can set other attributes by using AddAttribute() and
|
|
AddAttribBits() functions inherited from the base wxGLAttribsBase class.
|
|
While WGL_/GLX_/NS attributes can be added, PFD_ (for MSW) can not.
|
|
|
|
@since 3.1.0
|
|
|
|
@library{wxgl}
|
|
@category{gl}
|
|
|
|
@see wxGLCanvas, wxGLContext, wxGLAttribsBase, wxGLContextAttrs
|
|
*/
|
|
class wxGLAttributes : public wxGLAttribsBase
|
|
{
|
|
public:
|
|
/**
|
|
Use true colour instead of colour index rendering for each pixel.
|
|
It makes no effect for OS X.
|
|
*/
|
|
wxGLAttributes& RGBA();
|
|
|
|
/**
|
|
Specifies the number of bits for colour buffer. For RGBA it's
|
|
normally the sum of the bits per each component.
|
|
|
|
@param val
|
|
The number of bits.
|
|
*/
|
|
wxGLAttributes& BufferSize(int val);
|
|
|
|
/**
|
|
Specifies the framebuffer level. It makes no effect for OS X.
|
|
|
|
@param val
|
|
0 for main buffer, >0 for overlay, <0 for underlay.
|
|
*/
|
|
wxGLAttributes& Level(int val);
|
|
|
|
/**
|
|
Requests using double buffering.
|
|
*/
|
|
wxGLAttributes& DoubleBuffer();
|
|
|
|
/**
|
|
Use stereoscopic display.
|
|
*/
|
|
wxGLAttributes& Stereo();
|
|
|
|
/**
|
|
Specifies the number of auxiliary buffers.
|
|
|
|
@param val
|
|
The number of auxiliary buffers.
|
|
*/
|
|
wxGLAttributes& AuxBuffers(int val);
|
|
|
|
/**
|
|
Specifies the minimal number of bits for each colour and alpha.
|
|
On MSW and OSX this function also sets the size of the colour buffer.
|
|
|
|
@param mRed
|
|
The minimal number of bits for colour red.
|
|
@param mGreen
|
|
The minimal number of bits for colour green.
|
|
@param mBlue
|
|
The minimal number of bits for colour blue.
|
|
@param mAlpha
|
|
The minimal number of bits for alpha channel.
|
|
*/
|
|
wxGLAttributes& MinRGBA(int mRed, int mGreen, int mBlue, int mAlpha);
|
|
|
|
/**
|
|
Specifies number of bits for Z-buffer.
|
|
|
|
@param val
|
|
Number of bits for Z-buffer (typically 0, 16 or 32).
|
|
*/
|
|
wxGLAttributes& Depth(int val);
|
|
|
|
/**
|
|
Specifies number of bits for stencil buffer.
|
|
|
|
@param val
|
|
Number of bits.
|
|
*/
|
|
wxGLAttributes& Stencil(int val);
|
|
|
|
/**
|
|
Specifies the minimal number of bits for each accumulator channel.
|
|
On MSW and OSX this function also sets the size of the accumulation buffer.
|
|
|
|
@param mRed
|
|
The minimal number of bits for red accumulator.
|
|
@param mGreen
|
|
The minimal number of bits for green accumulator.
|
|
@param mBlue
|
|
The minimal number of bits for blue accumulator.
|
|
@param mAlpha
|
|
The minimal number of bits for alpha accumulator.
|
|
*/
|
|
wxGLAttributes& MinAcumRGBA(int mRed, int mGreen, int mBlue, int mAlpha);
|
|
|
|
/**
|
|
Use multi-sampling support (antialiasing).
|
|
|
|
@param val
|
|
Number of sample buffers, usually 1.
|
|
*/
|
|
wxGLAttributes& SampleBuffers(int val);
|
|
|
|
/**
|
|
Specifies the number of samplers per pixel.
|
|
|
|
@param val
|
|
Number of samplers, e.g. 4 for 2x2 antialiasing.
|
|
*/
|
|
wxGLAttributes& Samplers(int val);
|
|
|
|
/**
|
|
Used to request a frame buffer sRGB capable. It makes no effect for OS X.
|
|
*/
|
|
wxGLAttributes& FrameBuffersRGB();
|
|
|
|
/**
|
|
Set some typically needed attributes. E.g. full-acceleration on MSW.
|
|
|
|
@see Defaults()
|
|
*/
|
|
wxGLAttributes& PlatformDefaults();
|
|
|
|
/**
|
|
wxWidgets defaults:
|
|
RGBA, Z-depth 16 bits, double buffering, 1 sample buffer, 4 samplers.
|
|
|
|
@see PlatformDefaults()
|
|
*/
|
|
wxGLAttributes& Defaults();
|
|
|
|
/**
|
|
The set of attributes must end with this one; otherwise, the GPU may
|
|
display nothing at all.
|
|
*/
|
|
void EndList();
|
|
};
|
|
|
|
/**
|
|
@class wxGLContextAttrs
|
|
|
|
This class is used for setting context attributes.
|
|
Since OpenGL version 3.0 the ARB adds attributes time to time to the rendering
|
|
context functionality. wxWidgets implements attributes up to OGL 4.5, but
|
|
you can set new attributes by using AddAttribute() and AddAttribBits()
|
|
functions inherited from the base wxGLAttribsBase class.
|
|
|
|
Attributes can be chained. For example:
|
|
@code
|
|
wxGLContextAttrs cxtAttrs;
|
|
cxtAttrs.CoreProfile().OGLVersion(4, 5).Robust().ResetIsolation().EndList();
|
|
@endcode
|
|
|
|
Notice that EndList() must be used as the last attribute. Not adding it will
|
|
likely result in nothing displayed at all.
|
|
|
|
@since 3.1.0
|
|
|
|
@library{wxgl}
|
|
@category{gl}
|
|
|
|
@see wxGLCanvas, wxGLContext, wxGLAttribsBase, wxGLAttributes
|
|
*/
|
|
class wxGLContextAttrs : public wxGLAttribsBase
|
|
{
|
|
public:
|
|
/**
|
|
Request an OpenGL core profile for the context.
|
|
|
|
If the requested OpenGL version is less than 3.2, this attribute is
|
|
ignored and the functionality of the context is determined solely by
|
|
the requested version.
|
|
*/
|
|
wxGLContextAttrs& CoreProfile();
|
|
|
|
/**
|
|
Request specific OpenGL core major version number (>= 3).
|
|
|
|
@param val
|
|
The major version number requested.
|
|
|
|
It has no effect under OS X where specifying CoreProfile() will
|
|
result in using OpenGL version at least 3.2.
|
|
*/
|
|
wxGLContextAttrs& MajorVersion(int val);
|
|
|
|
/**
|
|
Request specific OpenGL core minor version number.
|
|
|
|
@param val
|
|
The minor version number requested, e.g. 2 if OpenGL 3.2 is requested.
|
|
|
|
It has no effect under OS X where specifying CoreProfile() will
|
|
result in using OpenGL version at least 3.2.
|
|
*/
|
|
wxGLContextAttrs& MinorVersion(int val);
|
|
|
|
/**
|
|
An easy way of requesting an OpenGL version.
|
|
|
|
@param vmayor
|
|
The major version number requested, e.g. 4 if OpenGL 4.5 is requested.
|
|
|
|
@param vminor
|
|
The minor version number requested, e.g. 5 if OpenGL 4.5 is requested.
|
|
|
|
It has no effect under OS X where specifying CoreProfile() will
|
|
result in using OpenGL version at least 3.2.
|
|
*/
|
|
wxGLContextAttrs& OGLVersion(int vmayor, int vminor);
|
|
|
|
/**
|
|
Request a type of context with all OpenGL features from version 1.0 to
|
|
the newest available by the GPU driver. In this mode the GPU may be some
|
|
slower than it would be without this compatibility attribute.
|
|
*/
|
|
wxGLContextAttrs& CompatibilityProfile();
|
|
|
|
/**
|
|
Request a forward-compatible context.
|
|
Forward-compatible contexts are defined only for OpenGL versions 3.0 and
|
|
later. They must not support functionality marked as deprecated or
|
|
removed by the requested version of the OpenGL API.
|
|
|
|
It has no effect under OS X.
|
|
*/
|
|
wxGLContextAttrs& ForwardCompatible();
|
|
|
|
/**
|
|
Request an ES or ES2 ("Embedded Subsystem") context. These are special
|
|
subsets of OpenGL, lacking some features of the full specification.
|
|
Used mainly in embedded devices such as mobile phones.
|
|
|
|
It has no effect under OS X.
|
|
*/
|
|
wxGLContextAttrs& ES2();
|
|
|
|
/**
|
|
Request debugging functionality. This tells OpenGL to prepare a set where
|
|
some logs are enabled and also allows OGL to send debug messages through
|
|
a callback function.
|
|
|
|
It has no effect under OS X.
|
|
*/
|
|
wxGLContextAttrs& DebugCtx();
|
|
|
|
/**
|
|
Request robustness, or how OpenGL handles out-of-bounds buffer object
|
|
accesses and graphics reset notification behaviours.
|
|
|
|
It has no effect under OS X.
|
|
*/
|
|
wxGLContextAttrs& Robust();
|
|
|
|
/**
|
|
With robustness enabled, never deliver notification of reset events.
|
|
|
|
It has no effect under OS X.
|
|
*/
|
|
wxGLContextAttrs& NoResetNotify();
|
|
|
|
/**
|
|
With robustness enabled, if graphics reset happens, all context state is
|
|
lost.
|
|
|
|
It has no effect under OS X.
|
|
*/
|
|
wxGLContextAttrs& LoseOnReset();
|
|
|
|
/**
|
|
Request OpenGL to protect other applications or shared contexts from reset
|
|
side-effects.
|
|
|
|
It has no effect under OS X.
|
|
*/
|
|
wxGLContextAttrs& ResetIsolation();
|
|
|
|
/**
|
|
Request OpenGL to avoid or not flushing pending commands when the context
|
|
is made no longer current (released). If you don't specify this attribute,
|
|
the GPU driver default is 'flushing'.
|
|
|
|
@param val
|
|
0 for not flushing, 1 (wxWidgets default) for flushing pending commands.
|
|
|
|
It has no effect under OS X.
|
|
*/
|
|
wxGLContextAttrs& ReleaseFlush(int val = 1);
|
|
|
|
/**
|
|
Set platform specific defaults. Currently only Unix defaults are
|
|
implemented: use X11 direct rendering and use X11 RGBA type.
|
|
*/
|
|
wxGLContextAttrs& PlatformDefaults();
|
|
|
|
/**
|
|
The set of attributes must end with this one; otherwise, the GPU may
|
|
display nothing at all.
|
|
*/
|
|
void EndList();
|
|
};
|
|
|
|
/**
|
|
@class wxGLContext
|
|
|
|
An instance of a wxGLContext represents the state of an OpenGL state
|
|
machine and the connection between OpenGL and the system.
|
|
|
|
The OpenGL state includes everything that can be set with the OpenGL API:
|
|
colors, rendering variables, buffer data ids, texture objects, etc. It is
|
|
possible to have multiple rendering contexts share buffer data and textures.
|
|
This feature is specially useful when the application use multiple threads
|
|
for updating data into the memory of the graphics card.
|
|
|
|
Whether one only rendering context is used with or bound to multiple output
|
|
windows or if each window has its own bound context is a developer decision.
|
|
It is important to take into account that GPU makers may set different pointers
|
|
to the same OGL function for different contexts. The way these pointers are
|
|
retrieved from the OGL driver should be used again for each new context.
|
|
|
|
Binding (making current) a rendering context with another instance of a
|
|
wxGLCanvas however works only if the both wxGLCanvas instances were created
|
|
with the same attributes.
|
|
|
|
OpenGL version 3 introduced a new type of specification profile, the modern
|
|
core profile. The old compatibility profile maintains all legacy features.
|
|
Since wxWidgets 3.1.0 you can choose the type of context and even ask for a
|
|
specified OGL version number. However, its advised to use only core profile
|
|
as the compatibility profile may run a bit slower.
|
|
|
|
OpenGL core profile specification defines several flags at context creation
|
|
that determine not only the type of context but also some features. Some of
|
|
these flags can be set in the list of attributes used at wxGLCanvas ctor.
|
|
But since wxWidgets 3.1.0 it is strongly encouraged to use the new mechanism:
|
|
setting the context attributes with a wxGLContextAttrs object and the canvas
|
|
attributes with a wxGLAttributes object.
|
|
|
|
The best way of knowing if your OpenGL environment supports a specific type
|
|
of context is creating a wxGLContext instance and checking wxGLContext::IsOK().
|
|
If it returns false, then simply delete that instance and create a new one
|
|
with other attributes.
|
|
|
|
wxHAS_OPENGL_ES is defined on platforms that only have this implementation
|
|
available (e.g. the iPhone) and don't support the full specification.
|
|
|
|
@library{wxgl}
|
|
@category{gl}
|
|
|
|
@see wxGLCanvas, wxGLContextAttrs, wxGLAttributes
|
|
*/
|
|
class wxGLContext : public wxObject
|
|
{
|
|
public:
|
|
/**
|
|
Constructor.
|
|
|
|
@param win
|
|
The canvas that is used to initialize this context. This parameter
|
|
is needed only temporarily, and the caller may do anything with it
|
|
(e.g. destroy the window) after the constructor returned. @n
|
|
It will be possible to bind (make current) this context to any
|
|
other wxGLCanvas that has been created with equivalent attributes
|
|
as win.
|
|
@param other
|
|
Context to share some data with or @NULL (the default) for no
|
|
sharing.
|
|
@param ctxAttrs
|
|
A wxGLContextAttrs pointer to the attributes used for defining the
|
|
flags when OGL >= 3.2 is requested. This is the preferred method
|
|
since wxWidgets 3.1.0. The previous method (still available for
|
|
backwards compatibility) is to define the attributes at wxGLCanvas
|
|
ctor. If this parameter is @NULL (the default) then that previous
|
|
method is taken.
|
|
If no attributes are defined at all, then those provided by the GPU
|
|
driver defaults will be used.
|
|
*/
|
|
wxGLContext(wxGLCanvas* win,
|
|
const wxGLContext* other = NULL,
|
|
const wxGLContextAttrs* ctxAttrs = NULL);
|
|
|
|
/**
|
|
Checks if the underlying OpenGL rendering context was correctly created
|
|
by the system with the requested attributes. If this function returns
|
|
@false then the wxGLContext object is useless and should be deleted and
|
|
recreated with different attributes.
|
|
|
|
@since 3.1.0
|
|
*/
|
|
bool IsOK();
|
|
|
|
/**
|
|
Makes the OpenGL state that is represented by this rendering context
|
|
current with the wxGLCanvas @e win.
|
|
|
|
@note @a win can be a different wxGLCanvas window than the one that was
|
|
passed to the constructor of this rendering context. If @e RC is
|
|
an object of type wxGLContext, the statements
|
|
@e "RC.SetCurrent(win);" and @e "win.SetCurrent(RC);" are
|
|
equivalent, see wxGLCanvas::SetCurrent().
|
|
*/
|
|
virtual bool SetCurrent(const wxGLCanvas& win) const;
|
|
};
|
|
|
|
/**
|
|
@anchor wxGL_FLAGS
|
|
|
|
Constants for use with wxGLCanvas. Most of the constants must be followed
|
|
by a value. This is indicated by "(F)".
|
|
Instead of these flags, the use of wxGLAttributes and wxGLContextAttrs is
|
|
preferred since wxWidgets 3.1.0.
|
|
|
|
@note Not all implementations support options such as stereo, auxiliary
|
|
buffers, alpha channel, and accumulator buffer, use
|
|
wxGLCanvas::IsDisplaySupported() to check for individual visual
|
|
attributes support.
|
|
*/
|
|
enum
|
|
{
|
|
/// Use true color (the default if no attributes at all are specified);
|
|
/// do not use a palette.
|
|
WX_GL_RGBA = 1,
|
|
|
|
/// (F) Specifies the number of bits for colour buffer.
|
|
WX_GL_BUFFER_SIZE,
|
|
|
|
/// (F) 0 for main buffer, >0 for overlay, <0 for underlay.
|
|
WX_GL_LEVEL,
|
|
|
|
/// Use double buffering if present ("on" if no attributes specified).
|
|
WX_GL_DOUBLEBUFFER,
|
|
|
|
/// Use stereoscopic display.
|
|
WX_GL_STEREO,
|
|
|
|
/// (F) The number of auxiliary buffers.
|
|
WX_GL_AUX_BUFFERS,
|
|
|
|
/// (F) Use red buffer with most bits (> MIN_RED bits)
|
|
WX_GL_MIN_RED,
|
|
|
|
/// (F) Use green buffer with most bits (> MIN_GREEN bits)
|
|
WX_GL_MIN_GREEN,
|
|
|
|
/// (F) Use blue buffer with most bits (> MIN_BLUE bits)
|
|
WX_GL_MIN_BLUE,
|
|
|
|
/// (F) Use alpha buffer with most bits (> MIN_ALPHA bits)
|
|
WX_GL_MIN_ALPHA,
|
|
|
|
/// (F) Specifies number of bits for Z-buffer (typically 0, 16 or 32).
|
|
WX_GL_DEPTH_SIZE,
|
|
|
|
/// (F) Specifies number of bits for stencil buffer.
|
|
WX_GL_STENCIL_SIZE,
|
|
|
|
/// (F) Specifies minimal number of red accumulator bits.
|
|
WX_GL_MIN_ACCUM_RED,
|
|
|
|
/// (F) Specifies minimal number of green accumulator bits.
|
|
WX_GL_MIN_ACCUM_GREEN,
|
|
|
|
/// (F) Specifies minimal number of blue accumulator bits.
|
|
WX_GL_MIN_ACCUM_BLUE,
|
|
|
|
/// (F) Specifies minimal number of alpha accumulator bits.
|
|
WX_GL_MIN_ACCUM_ALPHA,
|
|
|
|
/// (F) 1 for multi-sampling support (antialiasing)
|
|
WX_GL_SAMPLE_BUFFERS,
|
|
|
|
/// (F) 4 for 2x2 antialiasing supersampling on most graphics cards
|
|
WX_GL_SAMPLES,
|
|
|
|
/**
|
|
Used to request a frame buffer sRGB capable
|
|
|
|
@since 3.1.0
|
|
*/
|
|
WX_GL_FRAMEBUFFER_SRGB,
|
|
|
|
/**
|
|
(F) Request specific OpenGL core major version number (>= 3).
|
|
|
|
This attribute should be followed by the major version number
|
|
requested.
|
|
|
|
It has no effect under OS X where specifying ::WX_GL_CORE_PROFILE will
|
|
result in using OpenGL version at least 3.2 but can still be used
|
|
there for portability.
|
|
|
|
@since 3.0.3
|
|
*/
|
|
WX_GL_MAJOR_VERSION,
|
|
|
|
/**
|
|
(F) Request specific OpenGL core minor version number.
|
|
|
|
This attribute has the same semantics as ::WX_GL_MAJOR_VERSION but is
|
|
for the minor OpenGL version, e.g. 2 if OpenGL 3.2 is requested.
|
|
|
|
@since 3.0.3
|
|
*/
|
|
WX_GL_MINOR_VERSION,
|
|
|
|
/**
|
|
Request an OpenGL core profile for the context.
|
|
|
|
If the requested OpenGL version is less than 3.2, this attribute is
|
|
ignored and the functionality of the context is determined solely by
|
|
the requested version.
|
|
|
|
@since 3.0.3
|
|
*/
|
|
WX_GL_CORE_PROFILE,
|
|
|
|
/**
|
|
Request a type of context with all OpenGL features from version 1.0 to
|
|
the newest available by the GPU driver. In this mode the GPU may be some
|
|
slower than it would be without this compatibility attribute.
|
|
|
|
@since 3.1.0
|
|
*/
|
|
wx_GL_COMPAT_PROFILE,
|
|
|
|
/**
|
|
Request a forward-compatible context.
|
|
Forward-compatible contexts are defined only for OpenGL versions 3.0 and
|
|
later. They must not support functionality marked as deprecated by that
|
|
version of the OpenGL API.
|
|
|
|
@since 3.1.0
|
|
*/
|
|
WX_GL_FORWARD_COMPAT,
|
|
|
|
/**
|
|
Request an ES or ES2 ("Embedded Subsystem") context. These are special
|
|
subsets of OpenGL, lacking some features of the full specification.
|
|
Used mainly in embedded devices such as mobile phones.
|
|
|
|
@since 3.1.0
|
|
*/
|
|
WX_GL_ES2,
|
|
|
|
/**
|
|
Request debugging functionality. This tells OpenGL to prepare a set where
|
|
some logs are enabled and also allows OGL to send debug messages through
|
|
a callback function.
|
|
|
|
@since 3.1.0
|
|
*/
|
|
WX_GL_DEBUG,
|
|
|
|
/**
|
|
Request robustness, or how OpenGL handles out-of-bounds buffer object
|
|
accesses and graphics reset notification behaviours.
|
|
|
|
@since 3.1.0
|
|
*/
|
|
WX_GL_ROBUST_ACCESS,
|
|
|
|
/**
|
|
With robustness enabled, never deliver notification of reset events.
|
|
|
|
@since 3.1.0
|
|
*/
|
|
WX_GL_NO_RESET_NOTIFY,
|
|
|
|
/**
|
|
With robustness enabled, if graphics reset happens, all context state is
|
|
lost.
|
|
|
|
@since 3.1.0
|
|
*/
|
|
WX_GL_LOSE_ON_RESET,
|
|
|
|
/**
|
|
Request OpenGL to protect other apps or shared contexts from reset
|
|
side-effects.
|
|
|
|
@since 3.1.0
|
|
*/
|
|
WX_GL_RESET_ISOLATION,
|
|
|
|
/**
|
|
Request OpenGL to flush pending commands when the context is released.
|
|
|
|
@since 3.1.0
|
|
*/
|
|
WX_GL_RELEASE_FLUSH,
|
|
|
|
/**
|
|
Request OpenGL to avoid flushing pending commands when the context is released.
|
|
|
|
@since 3.1.0
|
|
*/
|
|
WX_GL_RELEASE_NONE
|
|
};
|
|
|
|
/**
|
|
@class wxGLCanvas
|
|
|
|
wxGLCanvas is a class for displaying OpenGL graphics. It is always used in
|
|
conjunction with wxGLContext as the context can only 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 wxGLContext that is initialized with this
|
|
wxGLCanvas and then later use either SetCurrent() with the instance of the
|
|
wxGLContext or wxGLContext::SetCurrent() with the instance of the
|
|
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 SwapBuffers() to swap the
|
|
buffers of the OpenGL canvas and thus show your current output.
|
|
|
|
Notice that versions of wxWidgets previous to 2.9 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 pass them
|
|
in the constructor using a wxGLAttributes instance. You can still use
|
|
the way before 3.1.0 (setting up the correct values of the @e attribList
|
|
parameter) but it's discouraged.
|
|
|
|
@note
|
|
On those platforms which use a configure script (e.g. Linux and OS X)
|
|
OpenGL support is automatically enabled if the relative headers and
|
|
libraries are found.
|
|
To switch it on under the other platforms (e.g. Windows), you need to edit
|
|
the @c setup.h file and set @c wxUSE_GLCANVAS to @c 1 and then also pass
|
|
@c USE_OPENGL=1 to the make utility. You may also need to add @c opengl32.lib
|
|
(and @c glu32.lib for old OpenGL versions) to the list of the libraries
|
|
your program is linked with.
|
|
|
|
@library{wxgl}
|
|
@category{gl}
|
|
|
|
@see wxGLContext, wxGLAttributes, wxGLContextAttrs
|
|
*/
|
|
class wxGLCanvas : public wxWindow
|
|
{
|
|
public:
|
|
/**
|
|
Creates a window with the given parameters. Notice that you need to
|
|
create and use a wxGLContext to output to this window.
|
|
|
|
@param parent
|
|
Pointer to a parent window.
|
|
@param dispAttrs
|
|
The wxGLAttributes used for setting display attributes (not for
|
|
rendering context attributes).
|
|
@param id
|
|
Window identifier. If -1, will automatically create an identifier.
|
|
@param pos
|
|
Window position. wxDefaultPosition is (-1, -1) which indicates that
|
|
wxWidgets should generate a default position for the window.
|
|
@param 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.
|
|
@param style
|
|
Window style.
|
|
@param name
|
|
Window name.
|
|
@param palette
|
|
Palette for indexed colour (i.e. non WX_GL_RGBA) mode. Ignored
|
|
under most platforms.
|
|
|
|
@since 3.1.0
|
|
*/
|
|
wxGLCanvas(wxWindow *parent,
|
|
const wxGLAttributes& dispAttrs,
|
|
wxWindowID id = wxID_ANY,
|
|
const wxPoint& pos = wxDefaultPosition,
|
|
const wxSize& size = wxDefaultSize,
|
|
long style = 0,
|
|
const wxString& name = wxGLCanvasName,
|
|
const wxPalette& palette = wxNullPalette);
|
|
|
|
/**
|
|
This constructor is still available only for compatibility reasons.
|
|
Please use the constructor with wxGLAttributes instead.
|
|
|
|
If @a attribList is not specified, wxGLAttributes::PlatformDefaults()
|
|
is used, plus some other attributes (see below).
|
|
|
|
@param 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 using @ref wxGL_FLAGS
|
|
constants. If a constant should be followed by a value, put it in
|
|
the next array position. For example, WX_GL_DEPTH_SIZE should be
|
|
followed by the value that indicates the number of bits for the
|
|
depth buffer, e.g.:
|
|
@code
|
|
attribList[n++] = WX_GL_DEPTH_SIZE;
|
|
attribList[n++] = 32;
|
|
attribList[n] = 0; // terminate the list
|
|
@endcode
|
|
If the attribute list is not specified at all, i.e. if this
|
|
parameter is @NULL, the default attributes including WX_GL_RGBA and
|
|
WX_GL_DOUBLEBUFFER are used. But notice that if you do specify some
|
|
attributes you also need to explicitly include these two default
|
|
attributes in the list if you need them.
|
|
*/
|
|
wxGLCanvas(wxWindow* parent, wxWindowID id = wxID_ANY,
|
|
const int* attribList = NULL,
|
|
const wxPoint& pos = wxDefaultPosition,
|
|
const wxSize& size = wxDefaultSize,
|
|
long style = 0,
|
|
const wxString& name = "GLCanvas",
|
|
const wxPalette& palette = wxNullPalette);
|
|
|
|
/**
|
|
Determines if a canvas having the specified attributes is available.
|
|
This only applies for visual attributes, not rendering context attributes.
|
|
|
|
@param dispAttrs
|
|
The requested attributes.
|
|
|
|
@return @true if attributes are supported.
|
|
|
|
@since 3.1.0
|
|
*/
|
|
static bool IsDisplaySupported(const wxGLAttributes& dispAttrs);
|
|
|
|
/**
|
|
Determines if a canvas having the specified attributes is available.
|
|
This only applies for visual attributes, not rendering context attributes.
|
|
Please, use the new form of this method, using wxGLAttributes.
|
|
|
|
@param attribList
|
|
See @a attribList for wxGLCanvas().
|
|
|
|
@return @true if attributes are supported.
|
|
*/
|
|
static bool IsDisplaySupported(const int* attribList);
|
|
|
|
/**
|
|
Returns true if the extension with given name is supported.
|
|
|
|
Notice that while this function is implemented for all of GLX, WGL and
|
|
NSOpenGL the extensions names are usually not the same for different
|
|
platforms and so the code using it still usually uses conditional
|
|
compilation.
|
|
*/
|
|
static bool IsExtensionSupported(const char *extension);
|
|
|
|
/**
|
|
Sets the current colour for this window (using @c glcolor3f()), using
|
|
the wxWidgets colour database to find a named colour.
|
|
*/
|
|
bool SetColour(const wxString& colour);
|
|
|
|
/**
|
|
Makes the OpenGL state that is represented by the OpenGL rendering
|
|
context @a context current, i.e. it will be used by all subsequent
|
|
OpenGL calls.
|
|
|
|
This is equivalent to wxGLContext::SetCurrent() called with this window
|
|
as parameter.
|
|
|
|
@note 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.
|
|
|
|
@return @false if an error occurred.
|
|
*/
|
|
bool SetCurrent(const wxGLContext& context) const;
|
|
|
|
/**
|
|
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.
|
|
|
|
@return @false if an error occurred.
|
|
*/
|
|
virtual bool SwapBuffers();
|
|
};
|