Abstraction of a graphics rendering context (GPU). More...

Classes
class	Stats
	Reports measured GPU performance and throughput. More...

class	VARState

Public Types
enum	{ MAX_LIGHTS = 2 }
	Maximum fixed-function lights supported. More...

enum	{ MAX_TRACKED_TEXTURE_UNITS = 2 }
	Maximum number of fixed-function texture units RenderDevice can use or track with pushed/popped render states. More...

enum	{ MAX_TRACKED_TEXTURE_IMAGE_UNITS = 2 }
	Maximum number of programmable pipeline texture image units RenderDevice can use or track with pushed/popped states. More...

enum	AlphaTest { ALPHA_GREATER = GL_GREATER, ALPHA_LESS = GL_LESS, ALPHA_GEQUAL = GL_GEQUAL, ALPHA_LEQUAL = GL_LEQUAL, ALPHA_NOTEQUAL = GL_NOTEQUAL, ALPHA_EQUAL = GL_EQUAL, ALPHA_ALWAYS_PASS = GL_ALWAYS, ALPHA_NEVER_PASS = GL_NEVER, ALPHA_CURRENT }
	This is provided for backwards compatibility. More...

enum	BlendEq { BLENDEQ_MIN = GL_MIN, BLENDEQ_MAX = GL_MAX, BLENDEQ_ADD = GL_FUNC_ADD, BLENDEQ_SUBTRACT = GL_FUNC_SUBTRACT, BLENDEQ_REVERSE_SUBTRACT = GL_FUNC_REVERSE_SUBTRACT, BLENDEQ_CURRENT, BLENDEQ_SAME_AS_RGB }

enum	BlendFunc { BLEND_SRC_ALPHA = GL_SRC_ALPHA, BLEND_ONE_MINUS_SRC_ALPHA = GL_ONE_MINUS_SRC_ALPHA, BLEND_DST_ALPHA = GL_DST_ALPHA, BLEND_ONE_MINUS_DST_ALPHA = GL_ONE_MINUS_DST_ALPHA, BLEND_ONE = GL_ONE, BLEND_ZERO = GL_ZERO, BLEND_SRC_COLOR = GL_SRC_COLOR, BLEND_DST_COLOR = GL_DST_COLOR, BLEND_ONE_MINUS_SRC_COLOR = GL_ONE_MINUS_SRC_COLOR, BLEND_ONE_MINUS_DST_COLOR = GL_ONE_MINUS_DST_COLOR, BLEND_CONSTANT_COLOR = GL_CONSTANT_COLOR, BLEND_ONE_MINUS_CONSTANT_COLOR = GL_ONE_MINUS_CONSTANT_COLOR, BLEND_CONSTANT_ALPHA = GL_CONSTANT_ALPHA, BLEND_ONE_MINUS_CONSTANT_ALPHA = GL_ONE_MINUS_CONSTANT_ALPHA, BLEND_CURRENT, BLEND_SAME_AS_RGB }

enum	DepthTest { DEPTH_GREATER = GL_GREATER, DEPTH_LESS = GL_LESS, DEPTH_GEQUAL = GL_GEQUAL, DEPTH_LEQUAL = GL_LEQUAL, DEPTH_NOTEQUAL = GL_NOTEQUAL, DEPTH_EQUAL = GL_EQUAL, DEPTH_ALWAYS_PASS = GL_ALWAYS, DEPTH_NEVER_PASS = GL_NEVER, DEPTH_CURRENT }

enum	DrawBuffer { DRAW_NONE = GL_NONE, DRAW_FRONT_LEFT = GL_FRONT_LEFT, DRAW_FRONT_RIGHT = GL_FRONT_RIGHT, DRAW_BACK_LEFT = GL_BACK_LEFT, DRAW_BACK_RIGHT = GL_BACK_RIGHT, DRAW_FRONT = GL_FRONT, DRAW_BACK = GL_BACK, DRAW_LEFT = GL_LEFT, DRAW_RIGHT = GL_RIGHT, DRAW_FRONT_AND_BACK = GL_FRONT_AND_BACK, DRAW_AUX0 = GL_AUX0, DRAW_AUX1 = GL_AUX1, DRAW_AUX2 = GL_AUX2, DRAW_AUX3 = GL_AUX3, DRAW_COLOR0 = GL_COLOR_ATTACHMENT0, DRAW_COLOR1 = GL_COLOR_ATTACHMENT1, DRAW_COLOR2 = GL_COLOR_ATTACHMENT2, DRAW_COLOR3 = GL_COLOR_ATTACHMENT3, DRAW_COLOR4 = GL_COLOR_ATTACHMENT4, DRAW_COLOR5 = GL_COLOR_ATTACHMENT5, DRAW_COLOR6 = GL_COLOR_ATTACHMENT6, DRAW_COLOR7 = GL_COLOR_ATTACHMENT7, DRAW_COLOR8 = GL_COLOR_ATTACHMENT8, DRAW_COLOR9 = GL_COLOR_ATTACHMENT9, DRAW_COLOR10 = GL_COLOR_ATTACHMENT10, DRAW_COLOR11 = GL_COLOR_ATTACHMENT11, DRAW_COLOR12 = GL_COLOR_ATTACHMENT12, DRAW_COLOR13 = GL_COLOR_ATTACHMENT13, DRAW_COLOR14 = GL_COLOR_ATTACHMENT14, DRAW_COLOR15 = GL_COLOR_ATTACHMENT15, DRAW_CURRENT }

enum	LogicOp { LOGIC_CLEAR = GL_CLEAR, LOGIC_AND = GL_AND, LOGIC_AND_REVERSE = GL_AND_REVERSE, LOGIC_COPY = GL_COPY, LOGIC_AND_INVERTED = GL_AND_INVERTED, LOGIC_NOOP = GL_NOOP, LOGIC_XOR = GL_XOR, LOGIC_OR = GL_OR, LOGIC_NOR = GL_NOR, LOGIC_EQUIV = GL_EQUIV, LOGIC_INVERT = GL_INVERT, LOGIC_OR_REVERSE = GL_OR_REVERSE, LOGIC_COPY_INVERTED = GL_COPY_INVERTED, LOGIC_OR_INVERTED = GL_OR_INVERTED, LOGIC_NAND = GL_NAND, LOGIC_SET = GL_SET, LOGICOP_CURRENT }

enum	ReadBuffer { READ_FRONT_LEFT = GL_FRONT_LEFT, READ_FRONT_RIGHT = GL_FRONT_RIGHT, READ_BACK_LEFT = GL_BACK_LEFT, READ_BACK_RIGHT = GL_BACK_RIGHT, READ_FRONT = GL_FRONT, READ_BACK = GL_BACK, READ_LEFT = GL_LEFT, READ_RIGHT = GL_RIGHT, READ_COLOR0 = GL_COLOR_ATTACHMENT0, READ_COLOR1 = GL_COLOR_ATTACHMENT1, READ_COLOR2 = GL_COLOR_ATTACHMENT2, READ_COLOR3 = GL_COLOR_ATTACHMENT3, READ_COLOR4 = GL_COLOR_ATTACHMENT4, READ_COLOR5 = GL_COLOR_ATTACHMENT5, READ_COLOR6 = GL_COLOR_ATTACHMENT6, READ_COLOR7 = GL_COLOR_ATTACHMENT7, READ_COLOR8 = GL_COLOR_ATTACHMENT8, READ_COLOR9 = GL_COLOR_ATTACHMENT9, READ_COLOR10 = GL_COLOR_ATTACHMENT10, READ_COLOR11 = GL_COLOR_ATTACHMENT11, READ_COLOR12 = GL_COLOR_ATTACHMENT12, READ_COLOR13 = GL_COLOR_ATTACHMENT13, READ_COLOR14 = GL_COLOR_ATTACHMENT14, READ_COLOR15 = GL_COLOR_ATTACHMENT15, READ_DEPTH = GL_DEPTH_ATTACHMENT, READ_STENCIL = GL_STENCIL_ATTACHMENT, READ_CURRENT }
	The constants that correspond to DrawBuffer have the same value, so that you can safely cast between them. More...

enum	RenderMode { RENDER_SOLID, RENDER_WIREFRAME, RENDER_POINTS, RENDER_CURRENT }

enum	ShadeMode { SHADE_FLAT = GL_FLAT, SHADE_SMOOTH = GL_SMOOTH, SHADE_CURRENT }

enum	StencilOp { STENCIL_INCR_WRAP = GL_INCR_WRAP, STENCIL_DECR_WRAP = GL_DECR_WRAP, STENCIL_KEEP = GL_KEEP, STENCIL_INCR = GL_INCR, STENCIL_DECR = GL_DECR, STENCIL_REPLACE = GL_REPLACE, STENCIL_ZERO = GL_ZERO, STENCIL_INVERT = GL_INVERT, STENCILOP_CURRENT }

enum	StencilTest { STENCIL_GREATER = GL_GREATER, STENCIL_LESS = GL_LESS, STENCIL_GEQUAL = GL_GEQUAL, STENCIL_LEQUAL = GL_LEQUAL, STENCIL_NOTEQUAL = GL_NOTEQUAL, STENCIL_EQUAL = GL_EQUAL, STENCIL_ALWAYS_PASS = GL_ALWAYS, STENCIL_NEVER_PASS = GL_NEVER, STENCIL_CURRENT }

Public Member Functions
	RenderDevice ()

	~RenderDevice ()

void	afterPrimitive ()
	Automatically called immediately after a primitive group. More...

AlphaTest	alphaTest () const

float	alphaTestReference () const

bool	alphaWrite () const
	Returns true if alphaWrite is enabled. More...

void	apply (const shared_ptr< class Shader > &s, Args &args)

void	apply (const shared_ptr< class Shader > &s)

void	beforePrimitive ()
	Automatically called immediately before a primitive group. More...

void	beginFrame ()
	Call to begin the rendering frame. More...

void	beginIndexedPrimitives ()

void	beginOpenGL ()
	Begin a section of raw OpenGL calls. More...

const CoordinateFrame &	cameraToWorldMatrix () const

void	cleanup ()
	Shuts down the rendering context. More...

void	clear (bool clearColor, bool clearDepth, bool clearStencil)
	To clear the alpha portion of the color buffer, remember to enable alpha write. More...

void	clear ()
	Clears color, depth, and stencil. More...

void	clearFramebuffer (bool clearColor=true, bool clearDepthAndStencil=true)
	Clears the drawbuffer to the specified clear values set in each attachment. More...

Rect2D	clip2D () const
	If enabled, returns the current clip region, othrwise the viewport. More...

const ImageFormat *	colorFormat () const
	Returns the format of the backbuffer/COLOR0 buffer (nullptr if there isn't such a buffer). More...

bool	colorWrite () const
	Returns true if colorWrite is enabled. More...

void	copyTextureFromScreen (const shared_ptr< Texture > &texture, const Rect2D &rect, const ImageFormat *format=nullptr, int mipLevel=0, CubeFace face=CubeFace::POS_X)

CullFace	cullFace () const

bool	currentDrawFramebufferComplete (String &whyIncomplete=dummyString) const
	Checks to ensure that the currently bound drawing framebuffer is complete and error free. More...

bool	currentReadFramebufferComplete (String &whyIncomplete=dummyString) const

bool	depthWrite () const
	Returns true if depthWrite is enabled. More...

void	describeSystem (TextOutput &t)
	Prints a human-readable description of this machine to the text output stream. More...

void	describeSystem (String &s)

DrawBuffer	drawBuffer () const

shared_ptr< Framebuffer >	drawFramebuffer () const
	Returns the framebuffer currently bound for drawing. More...

void	endFrame ()
	Call to end the current frame and schedules a OSWindow::swapGLBuffers call to occur some time before beginFrame. More...

void	endIndexedPrimitives ()

void	endOpenGL ()
	The state of the previous beginOpenGL is restored. More...

shared_ptr< Framebuffer >	framebuffer () const

void	getBlendFunc (Framebuffer::AttachmentPoint buf, BlendFunc &srcRGB, BlendFunc &dstRGB, BlendEq &eqRGB, BlendFunc &srcA, BlendFunc &dstA, BlendEq &eqA)

const String &	getCardDescription () const
	Description of the graphics card and driver version. More...

double	getDepthBufferValue (int x, int y) const
	Reads a depth buffer value (1 @ far plane, 0 @ near plane) from the given screen coordinates (x, y) where (0,0) is the top left corner of the width x height screen. More...

HDC	getWindowHDC () const

int	height () const
	Pixel dimensions of the OpenGL window interior More...

void	init (const OSWindow::Settings &settings=OSWindow::Settings())
	Automatically constructs a Win32Window (on Win32), X11Window (on Linux) or GLFWWindow (OS X) then calls the other init routine (provided for backwards compatibility). More...

void	init (OSWindow *window)
	The renderDevice will not delete the window on cleanup. More...

bool	initialized () const
	Returns true after RenderDevice::init has been called. More...

void	intersectClip2D (const Rect2D &clip)
	Intersects the current clipping (scissor) region with this one, which is specified in window coordinates. More...

bool	invertY () const
	True if the Y-axis has been flipped from the G3D convention, which occurs when the framebuffer is nullptr. More...

const Matrix4 &	invertYMatrix () const
	If G3D::RenderDevice::invertY() is true, this is the matrix is applied after the projection matrix to flip the y-axis. More...

void	issueMemoryBarrier (GLbitfield type)
	Wrapper for glMemoryBarrier(), type = GL_ALL_BARRIER_BITS. More...

void	majGLStateChange (int inc=1)
	State change to OpenGL (possibly because of a state change to RenderDevice). More...

void	majStateChange (int inc=1)
	State change to RenderDevice. More...

void	minGLStateChange (int inc=1)
	State change to OpenGL (possibly because of a state change to RenderDevice). More...

void	minStateChange (int inc=1)
	State change to RenderDevice. More...

CoordinateFrame	modelViewMatrix () const
	cameraToWorldMatrix().inverse() * objectToWorldMatrix() More...

Matrix4	modelViewProjectionMatrix () const
	projectionMatrix() * cameraToWorldMatrix().inverse() * objectToWorldMatrix() * invertYMatrix(). More...

void	modifyArgsForRectModeApply (Args &args)

Matrix4	objectToScreenMatrix () const
	invertYMatrix() * projectionMatrix() * objectToWorldMatrix() More...

const CoordinateFrame &	objectToWorldMatrix () const

void	pop2D ()

void	popState ()
	Restores all state to whatever was pushed previously. More...

Vector4	project (const Vector4 &v) const
	Multiplies v by the current object to world and world to camera matrices, then by the projection matrix to obtain a 2D point and z-value. More...

Vector4	project (const Vector3 &v) const

Matrix4	projectionMatrix () const
	The G3D projection matrix. More...

void	push2D ()

void	push2D (const shared_ptr< Framebuffer > &drawFramebuffer)
	Pushes all state, switches to the new framebuffer, and resizes the viewport and projection matrix accordingly. More...

void	push2D (const Rect2D &viewport)
	Set up for traditional 2D rendering (origin = upper left, y increases downwards). More...

void	pushState ()
	Checkmarks all RenderDevice state (anything that can be set using RenderDevice methods) except for the currently bound vertex arrays. More...

void	pushState (const shared_ptr< Framebuffer > &fb)
	Pushes the current state, then set the specified frame buffer and matches the viewport to it. More...

ReadBuffer	readBuffer () const

shared_ptr< Framebuffer >	readFramebuffer () const
	Returns the framebuffer currently bound for reading. More...

RenderMode	renderMode () const

void	resetState ()
	Sets all state to a clean rendering environment. More...

String	screenshot (const String &filepath="./") const
	Takes a JPG screenshot of the front buffer and saves it to a file. More...

shared_ptr< Image >	screenshotPic (bool getAlpha=false, bool invertY=true) const
	Takes a screenshot. More...

template<class T >
void	sendIndices (PrimitiveType primitive, int numIndices, const T *index)
	Draws the specified kind of primitive from the current vertex array. More...

void	sendIndices (PrimitiveType primitive, const IndexStream &indexStream)
	Send indices from an index buffer stored inside a vertex buffer. More...

template<class T >
void	sendIndices (PrimitiveType primitive, const Array< T > &index)
	Draws the specified kind of primitive from the current vertex array. More...

void	sendIndicesInstanced (PrimitiveType primitive, const IndexStream &indexStream, int numInstances)
	Send indices from an index buffer stored inside a vertex buffer. More...

void	sendMultidrawIndices (PrimitiveType primitive, const Array< IndexStream > &indexStreams, int numInstances, bool useInstances)
	Draws the specified kind of primitive using each one of the indexStreams. More...

void	sendMultidrawSequentialIndices (PrimitiveType primitive, const Array< int > &indexCounts, const Array< int > &indexOffsets)
	Draws the specified kind of primitive using sequential indices. More...

void	sendSequentialIndices (PrimitiveType primitive, int numVertices, int startVertex=0)
	Renders sequential vertices from the current vertex array. More...

void	sendSequentialIndicesInstanced (PrimitiveType primitive, int numVertices, int numInstances)
	Renders sequential vertices from the current vertex array for multiple instances. More...

void	setAlphaTest (AlphaTest test, float reference)
	If the alpha test is ALPHA_CURRENT, the reference is ignored. More...

void	setAlphaWrite (bool b)
	The frame buffer may optionally have an alpha channel for each pixel, depending on how the G3D::OSWindow was initialized (see G3D::RenderDevice::init, and G3D::OSWindow::Settings). More...

void	setBlendFunc (Framebuffer::AttachmentPoint buf, BlendFunc srcRGB, BlendFunc dstRGB, BlendEq eqRGB=BLENDEQ_ADD, BlendFunc srcA=BLEND_SAME_AS_RGB, BlendFunc dstA=BLEND_SAME_AS_RGB, BlendEq eqA=BLENDEQ_SAME_AS_RGB)
	Equivalent to glBlendFunc and glBlendEquation. More...

void	setBlendFunc (BlendFunc src, BlendFunc dst, BlendEq eqRGB=BLENDEQ_ADD, BlendEq eqA=BLENDEQ_SAME_AS_RGB, Framebuffer::AttachmentPoint buf=Framebuffer::COLOR0)

void	setCameraToWorldMatrix (const CoordinateFrame &cFrame)
	See RenderDevice::setObjectToWorldMatrix. More...

void	setClip2D (const Rect2D &clip)
	Sets a 2D clipping region (OpenGL scissor region) relative to the current window dimensions (not the viewport). More...

void	setColorClearValue (const Color4 &c)

void	setColorWrite (bool b)
	Color writing is on by default. More...

void	setCullFace (CullFace f)
	Equivalent to glCullFace. More...

void	setDebugOutput (bool b)
	Set OSWindow::Settings::debugContext = true and then set this to true to enable OpenGL debugging output. More...

void	setDepthClearValue (float d)

void	setDepthRange (float low, float high)

void	setDepthTest (DepthTest test)
	Use ALWAYS_PASS to shut off testing. More...

void	setDepthWrite (bool b)
	Defaults to true. More...

void	setDrawBuffer (DrawBuffer drawBuffer)
	Sets the frame buffer that is written to. More...

void	setDrawFramebuffer (const shared_ptr< Framebuffer > &fbo)
	Sets the framebuffer to render to. More...

void	setFramebuffer (const shared_ptr< Framebuffer > &fb)
	Sets both the draw and read framebuffers. More...

void	setGuardBandClip2D (const Vector2int16 thickness)
	Sets a clip2D region that is inset from the current framebuffer's boundaries by thickness. More...

void	setInvertY (bool i)
	Override the invertY() flag, which is normally set automatically by calls to setFramebuffer. More...

void	setLogicOp (const LogicOp op)
	Equivalent to glLogicOp call. More...

void	setObjectToWorldMatrix (const CoordinateFrame &cFrame)
	This is not the OpenGL MODELVIEW matrix: it is a matrix that maps object space to world space. More...

void	setPointSize (float diameter)
	Equivalent to glPointSize. More...

void	setPolygonOffset (float offset)
	Equivalent to glPolygonOffset More...

void	setProjectionAndCameraMatrix (const Projection &p, const CFrame &c)
	Setting both simultaneously minimizes OpenGL state changes. More...

void	setProjectionMatrix (const Matrix4 &P)
	To set a typical 3D perspective matrix, use either. More...

void	setProjectionMatrix (const class Projection &P)

void	setReadBuffer (ReadBuffer readBuffer)

void	setReadFramebuffer (const shared_ptr< Framebuffer > &fbo)

void	setRenderMode (RenderMode mode)

void	setSRGBConversion (bool b)
	By default, opengl does not covert writes to an sRGB texture into sRGB color space. More...

void	setStencilClearValue (int s)

void	setStencilConstant (int reference)
	Sets the constant used in the stencil test and operation (if op == STENCIL_REPLACE) More...

void	setStencilOp (StencilOp fail, StencilOp zfail, StencilOp zpass)
	If wrapping is not supported on the device, the nearest mode is selected. More...

void	setStencilOp (StencilOp frontStencilFail, StencilOp frontZFail, StencilOp frontZPass, StencilOp backStencilFail, StencilOp backZFail, StencilOp backZPass)
	When GLCaps::GL_ARB_stencil_two_side is true, separate stencil operations can be used for front and back faces. More...

void	setStencilTest (StencilTest test)

void	setSwapBuffersAutomatically (bool b)
	By default, OSWindow::swapGLBuffers is invoked automatically between RenderDevice::endFrame and the following RenderDevice::beginFrame to update the front buffer (what the user sees) from the back buffer (where rendering commands occur). More...

void	setVertexAttribArray (unsigned int attribNum, const class AttributeArray &v)
	Vertex attributes are a generalization of the various per-vertex attributes that relaxes the format restrictions. More...

void	setViewport (const Rect2D &v)
	(0, 0) is the upper-left corner of the screen. More...

void	setWindow (OSWindow *window)
	Sets the OSWindow used by this RenderDevice. More...

ShadeMode	shadeMode () const

bool	sRGBConversion () const

const Stats &	stats ()

StencilTest	stencilTest () const

void	swapBuffers ()
	Manually swap the front and back buffers. More...

bool	swapBuffersAutomatically () const

const Stopwatch &	swapBufferTimer () const
	Measures the amount of time spent in swapBuffers. More...

void	unsetVertexAttribArray (unsigned int attribNum)
	Counterpart to setVertexAttribArray. More...

const Rect2D &	viewport () const

int	width () const
	Pixel dimensions of the OpenGL window interior More...

OSWindow *	window () const
	Returns the OSWindow used by this RenderDevice. More...

const CoordinateFrame &	worldToCameraMatrix () const

Static Public Attributes
static thread_local RenderDevice *	current
	RenderDevice active on this thread, nullptr if there is not one. More...

Protected Attributes
RealTime	m_lastTime
	Time at which the previous endFrame() was called. More...

Stats	m_previousFrameStats
	Latched in swapbufers. More...

Stats	m_stats

Stopwatch	m_swapTimer
	Times swapBuffers. More...

Array< AttributeArray >	m_tempVAR
	Storage for setVARs. More...

VARState	m_varState
	Note: note backed up by push/pop, since push/pop can't be called inside indexed primitives. More...

Friends
class	AttributeArray

class	Framebuffer

class	Milestone

class	UserInput

class	VertexBuffer

Detailed Description

Abstraction of a graphics rendering context (GPU).

Implemented with an OpenGL context, but designed so that it can support other APIs (e.g., OpenGL ES, DirectX) as back ends.

Unlike OpenGL, in release mode, no RenderDevice call will trigger a pipeline flush, and all redundant state calls are automatically detected and optimized out. This includes queries: reading any RenderDevice state is instantaneous and does not flush the GPU (unlike glGet*).

In future releases, fixed function state will either be removed or isolated in RenderDevice. Wherever possible, structure your code to use Framebuffer, AttributeArray, and Shader instead of fixed-function.

You must call RenderDevice::init() before using the RenderDevice.

OpenGL is a basically good API with some rough spots. Three of these are addressed by RenderDevice. First, OpenGL state management is both tricky and potentially slow. Second, OpenGL functions are difficult to use because many extensions have led to an evolutionary rather than designed API. For type safety, new enums are introduced for values instead of the traditional OpenGL GLenum's, which are just ints. Third, OpenGL intialization is complicated. This interface simplifies it significantly.

NICEST line and point smoothing is enabled by default (however, you need to set your alpha blending mode to see it).

glEnable(GL_NORMALIZE) is set by default. glEnable(GL_COLOR_MATERIAL) is enabled by default. You may be able to get a slight speed increase by disabling GL_NORMALIZE or using GL_SCALE_NORMAL instead.

Fixed-function code is currently being phased out of the G3D API as it is deprecated in OpenGL. Shader and VertexArray code is the preferred rendering path.

Example

  RenderDevice renderDevice = new RenderDevice();
  renderDevice->init(OSWindow::Settings());

G3D::RenderDevice supports "X_CURRENT" as an option for most settings.

Stereo Rendering

For stereo rendering, set OSWindow::Settings::stereo = true and use RenderDevice::setDrawBuffer to switch which eye is being rendered. Only use RenderDevice::beginFrame / RenderDevice::endFrame once per frame, but do clear both buffers separately.

You can render in stereo (on a stereo capable card) by rendering twice, once for each eye's buffer:

   void onGraphics(...) {
       rd->setDrawBuffer(RenderDevice::DRAW_LEFT); 
       for (int count = 0; count < 2; ++count) {
          ... (put your normal rendering code here)
          rd->setDrawBuffer(RenderDevice::DRAW_RIGHT);
       }
   }

Multiple displays If you are using multiple synchronized displays (e.g. the CAVE), see: http://www.nvidia.com/object/IO_10753.html and http://www.cs.unc.edu/Research/stc/FAQs/nVidia/FrameLock-V1.0C.pdf

GLCaps loads the relevant extensions for you, but you must make the synchronizing calls yourself (typically, immediately before you call swap buffers).

Raw OpenGL Calls RenderDevice allows you to mix your own OpenGL calls with RenderDevice calls. It assumes that you restored the OpenGL state after your OpenGL calls, however. It is not safe to mix arbitrary OpenGL calls with Shaders, however. The G3D::Shader API supports more features than OpenGL shaders and does not work well with low-level OpenGL. You may find that the "wrong" shader is bound when you execute OpenGL calls.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Maximum fixed-function lights supported.

Deprecated:: Use a Shader

Enumerator
MAX_LIGHTS

◆ anonymous enum

anonymous enum

Maximum number of fixed-function texture units RenderDevice can use or track with pushed/popped render states.

This affects texture combine, matrix and LOD bias as well.

The maximum number of tracked units may be lower than hardware limits due to the cost of tracking and restoring the state. Most users will not use more, but increasing this value is the only necessary change.

Deprecated:

Enumerator
MAX_TRACKED_TEXTURE_UNITS

◆ anonymous enum

anonymous enum

Maximum number of programmable pipeline texture image units RenderDevice can use or track with pushed/popped states.

These are typically more than the fixed-function units.

The maximum number of tracked units may be lower than hardware limits due to the cost of tracking and restoring the state. Most users will not use more, but increasing this value is the only necessary change.

Enumerator
MAX_TRACKED_TEXTURE_IMAGE_UNITS

◆ AlphaTest

enum G3D::RenderDevice::AlphaTest

This is provided for backwards compatibility.

See also: OSWindow::Settings::enableAlphaTesting

Enumerator
ALPHA_GREATER
ALPHA_LESS
ALPHA_GEQUAL
ALPHA_LEQUAL
ALPHA_NOTEQUAL
ALPHA_EQUAL
ALPHA_ALWAYS_PASS
ALPHA_NEVER_PASS
ALPHA_CURRENT

◆ BlendEq

enum G3D::RenderDevice::BlendEq

Enumerator
BLENDEQ_MIN
BLENDEQ_MAX
BLENDEQ_ADD
BLENDEQ_SUBTRACT
BLENDEQ_REVERSE_SUBTRACT
BLENDEQ_CURRENT	Only legal for use in setBlendFunc.
BLENDEQ_SAME_AS_RGB

◆ BlendFunc

enum G3D::RenderDevice::BlendFunc

Enumerator
BLEND_SRC_ALPHA
BLEND_ONE_MINUS_SRC_ALPHA
BLEND_DST_ALPHA
BLEND_ONE_MINUS_DST_ALPHA
BLEND_ONE
BLEND_ZERO
BLEND_SRC_COLOR
BLEND_DST_COLOR
BLEND_ONE_MINUS_SRC_COLOR
BLEND_ONE_MINUS_DST_COLOR
BLEND_CONSTANT_COLOR
BLEND_ONE_MINUS_CONSTANT_COLOR
BLEND_CONSTANT_ALPHA
BLEND_ONE_MINUS_CONSTANT_ALPHA
BLEND_CURRENT	Only legal for use in setBlendFunc.
BLEND_SAME_AS_RGB

◆ DepthTest

enum G3D::RenderDevice::DepthTest

Enumerator
DEPTH_GREATER
DEPTH_LESS
DEPTH_GEQUAL
DEPTH_LEQUAL
DEPTH_NOTEQUAL
DEPTH_EQUAL
DEPTH_ALWAYS_PASS
DEPTH_NEVER_PASS
DEPTH_CURRENT

◆ DrawBuffer

enum G3D::RenderDevice::DrawBuffer

See also: drawBuffer()

Enumerator
DRAW_NONE
DRAW_FRONT_LEFT
DRAW_FRONT_RIGHT
DRAW_BACK_LEFT
DRAW_BACK_RIGHT
DRAW_FRONT
DRAW_BACK
DRAW_LEFT
DRAW_RIGHT
DRAW_FRONT_AND_BACK
DRAW_AUX0
DRAW_AUX1
DRAW_AUX2
DRAW_AUX3
DRAW_COLOR0
DRAW_COLOR1
DRAW_COLOR2
DRAW_COLOR3
DRAW_COLOR4
DRAW_COLOR5
DRAW_COLOR6
DRAW_COLOR7
DRAW_COLOR8
DRAW_COLOR9
DRAW_COLOR10
DRAW_COLOR11
DRAW_COLOR12
DRAW_COLOR13
DRAW_COLOR14
DRAW_COLOR15
DRAW_CURRENT

◆ LogicOp

enum G3D::RenderDevice::LogicOp

Enumerator
LOGIC_CLEAR
LOGIC_AND
LOGIC_AND_REVERSE
LOGIC_COPY
LOGIC_AND_INVERTED
LOGIC_NOOP
LOGIC_XOR
LOGIC_OR
LOGIC_NOR
LOGIC_EQUIV
LOGIC_INVERT
LOGIC_OR_REVERSE
LOGIC_COPY_INVERTED
LOGIC_OR_INVERTED
LOGIC_NAND
LOGIC_SET
LOGICOP_CURRENT

◆ ReadBuffer

enum G3D::RenderDevice::ReadBuffer

The constants that correspond to DrawBuffer have the same value, so that you can safely cast between them.

All have the corresponding OpenGL constant.

See also: readBuffer()

Enumerator
READ_FRONT_LEFT
READ_FRONT_RIGHT
READ_BACK_LEFT
READ_BACK_RIGHT
READ_FRONT
READ_BACK
READ_LEFT
READ_RIGHT
READ_COLOR0
READ_COLOR1
READ_COLOR2
READ_COLOR3
READ_COLOR4
READ_COLOR5
READ_COLOR6
READ_COLOR7
READ_COLOR8
READ_COLOR9
READ_COLOR10
READ_COLOR11
READ_COLOR12
READ_COLOR13
READ_COLOR14
READ_COLOR15
READ_DEPTH
READ_STENCIL
READ_CURRENT

◆ RenderMode

enum G3D::RenderDevice::RenderMode

See also: RenderDevice::setRenderMode

Enumerator
RENDER_SOLID
RENDER_WIREFRAME
RENDER_POINTS
RENDER_CURRENT	preserve whatever the render mode is currently set to.

◆ ShadeMode

enum G3D::RenderDevice::ShadeMode

Enumerator
SHADE_FLAT
SHADE_SMOOTH
SHADE_CURRENT

◆ StencilOp

enum G3D::RenderDevice::StencilOp

Enumerator
STENCIL_INCR_WRAP
STENCIL_DECR_WRAP
STENCIL_KEEP
STENCIL_INCR
STENCIL_DECR
STENCIL_REPLACE
STENCIL_ZERO
STENCIL_INVERT
STENCILOP_CURRENT

◆ StencilTest

enum G3D::RenderDevice::StencilTest

Enumerator
STENCIL_GREATER
STENCIL_LESS
STENCIL_GEQUAL
STENCIL_LEQUAL
STENCIL_NOTEQUAL
STENCIL_EQUAL
STENCIL_ALWAYS_PASS
STENCIL_NEVER_PASS
STENCIL_CURRENT

Constructor & Destructor Documentation

◆ RenderDevice()

G3D::RenderDevice::RenderDevice ( )

◆ ~RenderDevice()

G3D::RenderDevice::~RenderDevice ( )

Member Function Documentation

◆ afterPrimitive()

void G3D::RenderDevice::afterPrimitive ( )

Automatically called immediately after a primitive group.

◆ alphaTest()

AlphaTest G3D::RenderDevice::alphaTest ( ) const

◆ alphaTestReference()

float G3D::RenderDevice::alphaTestReference ( ) const

◆ alphaWrite()

bool G3D::RenderDevice::alphaWrite ( ) const

Returns true if alphaWrite is enabled.

◆ apply() [1/2]

void G3D::RenderDevice::apply	(	const shared_ptr< class Shader > &	s,
		Args &	args
	)

Referenced by apply().

◆ apply() [2/2]

void G3D::RenderDevice::apply ( const shared_ptr< class Shader > & s )

inline

◆ beforePrimitive()

void G3D::RenderDevice::beforePrimitive ( )

Automatically called immediately before a primitive group.

User code should only call this if making raw OpenGL calls (i.e., "glBegin"), in which case it should be called immediately before the glBegin and afterPrimitve should be called immediately after the glEnd.

◆ beginFrame()

void G3D::RenderDevice::beginFrame ( )

Call to begin the rendering frame.

◆ beginIndexedPrimitives()

void G3D::RenderDevice::beginIndexedPrimitives ( )

◆ beginOpenGL()

void G3D::RenderDevice::beginOpenGL ( )

Begin a section of raw OpenGL calls.

All RenderDevice state is synchronized with OpenGL and backed up.

You can always make raw OpenGL calls with G3D, however in some cases RenderDevice makes lazy state changes and you'll be surprised by the outcome. This lets you switch to a pure OpenGL mode. Do not make other RenderDevice calls while in beginOpenGL...endOpenGL.

◆ cameraToWorldMatrix()

const CoordinateFrame& G3D::RenderDevice::cameraToWorldMatrix ( ) const

◆ cleanup()

void G3D::RenderDevice::cleanup ( )

Shuts down the rendering context.

This should be the last call you make.

◆ clear() [1/2]

void G3D::RenderDevice::clear	(	bool	clearColor,
		bool	clearDepth,
		bool	clearStencil
	)

To clear the alpha portion of the color buffer, remember to enable alpha write.

◆ clear() [2/2]

void G3D::RenderDevice::clear ( )

inline

Clears color, depth, and stencil.

◆ clearFramebuffer()

void G3D::RenderDevice::clearFramebuffer	(	bool	clearColor = `true`,
		bool	clearDepthAndStencil = `true`
	)

Clears the drawbuffer to the specified clear values set in each attachment.

◆ clip2D()

Rect2D G3D::RenderDevice::clip2D ( ) const

If enabled, returns the current clip region, othrwise the viewport.

Referenced by intersectClip2D().

◆ colorFormat()

const ImageFormat* G3D::RenderDevice::colorFormat ( ) const

Returns the format of the backbuffer/COLOR0 buffer (nullptr if there isn't such a buffer).

◆ colorWrite()

bool G3D::RenderDevice::colorWrite ( ) const

Returns true if colorWrite is enabled.

◆ copyTextureFromScreen()

void G3D::RenderDevice::copyTextureFromScreen	(	const shared_ptr< Texture > &	texture,
		const Rect2D &	rect,
		const ImageFormat *	format = `nullptr`,
		int	mipLevel = `0`,
		CubeFace	face = `CubeFace::POS_X`
	)

Parameters

format If nullptr, defaults to texture->format()

◆ cullFace()

CullFace G3D::RenderDevice::cullFace ( ) const

inline

◆ currentDrawFramebufferComplete()

bool G3D::RenderDevice::currentDrawFramebufferComplete ( String & whyIncomplete = dummyString ) const

inline

Checks to ensure that the currently bound drawing framebuffer is complete and error free.

Returns: false On Incomplete Framebuffer Error; true On Complete Framebuffer

Referenced by sendIndices().

◆ currentReadFramebufferComplete()

bool G3D::RenderDevice::currentReadFramebufferComplete ( String & whyIncomplete = dummyString ) const

inline

◆ depthWrite()

bool G3D::RenderDevice::depthWrite ( ) const

Returns true if depthWrite is enabled.

◆ describeSystem() [1/2]

void G3D::RenderDevice::describeSystem ( TextOutput & t )

Prints a human-readable description of this machine to the text output stream.

Either argument may be nullptr.

◆ describeSystem() [2/2]

void G3D::RenderDevice::describeSystem ( String & s )

◆ drawBuffer()

DrawBuffer G3D::RenderDevice::drawBuffer ( ) const

inline

◆ drawFramebuffer()

shared_ptr<Framebuffer> G3D::RenderDevice::drawFramebuffer ( ) const

inline

Returns the framebuffer currently bound for drawing.

◆ endFrame()

void G3D::RenderDevice::endFrame ( )

Call to end the current frame and schedules a OSWindow::swapGLBuffers call to occur some time before beginFrame.

Because that swapGLBuffers might not actually occur until the next beginFrame, there is up to one frame of latency on the image displayed. This allows the CPU to execute while the GPU is still rendering, providing net higher performance.

◆ endIndexedPrimitives()

void G3D::RenderDevice::endIndexedPrimitives ( )

◆ endOpenGL()

void G3D::RenderDevice::endOpenGL ( )

The state of the previous beginOpenGL is restored.

◆ framebuffer()

shared_ptr<Framebuffer> G3D::RenderDevice::framebuffer ( ) const

inline

Deprecated:: Use drawFramebuffer() or readFramebuffer()

◆ getBlendFunc()

void G3D::RenderDevice::getBlendFunc	(	Framebuffer::AttachmentPoint	buf,
		BlendFunc &	srcRGB,
		BlendFunc &	dstRGB,
		BlendEq &	eqRGB,
		BlendFunc &	srcA,
		BlendFunc &	dstA,
		BlendEq &	eqA
	)

inline

◆ getCardDescription()

const String& G3D::RenderDevice::getCardDescription ( ) const

Description of the graphics card and driver version.

◆ getDepthBufferValue()

double G3D::RenderDevice::getDepthBufferValue	(	int	x,
		int	y
	)		const

Reads a depth buffer value (1 @ far plane, 0 @ near plane) from the given screen coordinates (x, y) where (0,0) is the top left corner of the width x height screen.

Result is undefined for x, y not on screen.

The result is sensitive to the projection and camera to world matrices.

If you need to read back the entire depth buffer, use OpenGL glReadPixels calls instead of many calls to getDepthBufferValue.

◆ getWindowHDC()

HDC G3D::RenderDevice::getWindowHDC ( ) const

◆ height()

int G3D::RenderDevice::height ( ) const

Pixel dimensions of the OpenGL window interior

Referenced by setGuardBandClip2D().

◆ init() [1/2]

void G3D::RenderDevice::init ( const OSWindow::Settings & settings = OSWindow::Settings() )

Automatically constructs a Win32Window (on Win32), X11Window (on Linux) or GLFWWindow (OS X) then calls the other init routine (provided for backwards compatibility).

The constructed window is deleted on shutdown.

◆ init() [2/2]

void G3D::RenderDevice::init ( OSWindow * window )

The renderDevice will not delete the window on cleanup.

◆ initialized()

bool G3D::RenderDevice::initialized ( ) const

Returns true after RenderDevice::init has been called.

◆ intersectClip2D()

void G3D::RenderDevice::intersectClip2D ( const Rect2D & clip )

inline

Intersects the current clipping (scissor) region with this one, which is specified in window coordinates.

See also: setGuardBandClip2D, setClip2D, clip2D

◆ invertY()

bool G3D::RenderDevice::invertY ( ) const

True if the Y-axis has been flipped from the G3D convention, which occurs when the framebuffer is nullptr.

By default, RenderDevice conventions assume that you are rendering to a G3D::Texture in a G3D::Framebuffer, so it configures the projection matrix and polygon winding direction so that the upper-left corner of the framebuffer is texel (0, 0).
When rendering directly to the screen, the opposite convention is needed. In this case, G3D applies an extra invertYMatrix() that flips the Y axis and internally inverts the winding conventions.

◆ invertYMatrix()

const Matrix4& G3D::RenderDevice::invertYMatrix ( ) const

If G3D::RenderDevice::invertY() is true, this is the matrix is applied after the projection matrix to flip the y-axis.

Otherwise it is the identity matrix.

◆ issueMemoryBarrier()

void G3D::RenderDevice::issueMemoryBarrier ( GLbitfield type )

Wrapper for glMemoryBarrier(), type = GL_ALL_BARRIER_BITS.

◆ majGLStateChange()

void G3D::RenderDevice::majGLStateChange ( int inc = 1 )

inline

State change to OpenGL (possibly because of a state change to RenderDevice).

Use to update the state change statistics when raw OpenGL calls are made.

◆ majStateChange()

void G3D::RenderDevice::majStateChange ( int inc = 1 )

inline

State change to RenderDevice.

Use to update the state change statistics when raw OpenGL calls are made.

Referenced by setDepthRange().

◆ minGLStateChange()

void G3D::RenderDevice::minGLStateChange ( int inc = 1 )

inline

State change to OpenGL (possibly because of a state change to RenderDevice).

Use to update the state change statistics when raw OpenGL calls are made.

Referenced by setAlphaWrite(), setColorWrite(), setDepthRange(), and setDepthWrite().

◆ minStateChange()

void G3D::RenderDevice::minStateChange ( int inc = 1 )

inline

State change to RenderDevice.

Use to update the state change statistics when raw OpenGL calls are made.

Referenced by setAlphaWrite(), setColorWrite(), and setDepthWrite().

◆ modelViewMatrix()

CoordinateFrame G3D::RenderDevice::modelViewMatrix ( ) const

cameraToWorldMatrix().inverse() * objectToWorldMatrix()

◆ modelViewProjectionMatrix()

Matrix4 G3D::RenderDevice::modelViewProjectionMatrix ( ) const

projectionMatrix() * cameraToWorldMatrix().inverse() * objectToWorldMatrix() * invertYMatrix().

◆ modifyArgsForRectModeApply()

void G3D::RenderDevice::modifyArgsForRectModeApply ( Args & args )

◆ objectToScreenMatrix()

Matrix4 G3D::RenderDevice::objectToScreenMatrix ( ) const

invertYMatrix() * projectionMatrix() * objectToWorldMatrix()

◆ objectToWorldMatrix()

const CoordinateFrame& G3D::RenderDevice::objectToWorldMatrix ( ) const

◆ pop2D()

void G3D::RenderDevice::pop2D ( )

◆ popState()

void G3D::RenderDevice::popState ( )

Restores all state to whatever was pushed previously.

Push and pop must be used in matching pairs.

◆ project() [1/2]

Vector4 G3D::RenderDevice::project ( const Vector4 & v ) const

Multiplies v by the current object to world and world to camera matrices, then by the projection matrix to obtain a 2D point and z-value.

The result is the 2D position to which the 3D point v corresponds. You can use this to make results rendered with push2D() line up with those rendered with a 3D transformation.

The value returned is relative to the current viewport.

See G3D::glToScreen

◆ project() [2/2]

Vector4 G3D::RenderDevice::project ( const Vector3 & v ) const

◆ projectionMatrix()

Matrix4 G3D::RenderDevice::projectionMatrix ( ) const

The G3D projection matrix.

Does not include the invertYMatrix(). Note that this is not equal to the GLSL gl_ProjectionMatrix.

See also: G3D::Projection

◆ push2D() [1/3]

void G3D::RenderDevice::push2D ( )

◆ push2D() [2/3]

void G3D::RenderDevice::push2D ( const shared_ptr< Framebuffer > & drawFramebuffer )

Pushes all state, switches to the new framebuffer, and resizes the viewport and projection matrix accordingly.

◆ push2D() [3/3]

void G3D::RenderDevice::push2D ( const Rect2D & viewport )

Set up for traditional 2D rendering (origin = upper left, y increases downwards).

Note: the viewport will range up to the number of pixels (e.g., (0,0)-(640,480)), as recommended in http://msdn.microsoft.com/library/default.asp?url=/library/en-us/opengl/apptips_7wqb.asp . Push2D also translates (sets the cameraToWorldMatrix) by (0.375, 0.375, 0) as recommended in the OpenGL manual. This helps avoid rasterization holes due to float-to-int roundoff.

◆ pushState() [1/2]

void G3D::RenderDevice::pushState ( )

Checkmarks all RenderDevice state (anything that can be set using RenderDevice methods) except for the currently bound vertex arrays.

If you are using some other OpenGL state that is not covered by any of the above (e.g., the glReadBuffer and other buffer options), you can call glPushAttrib(GL_ALL_ATTRIB_BITS) immediately before pushState to ensure that it is pushed as well.

◆ pushState() [2/2]

void G3D::RenderDevice::pushState ( const shared_ptr< Framebuffer > & fb )

Pushes the current state, then set the specified frame buffer and matches the viewport to it.

◆ readBuffer()

ReadBuffer G3D::RenderDevice::readBuffer ( ) const

inline

◆ readFramebuffer()

shared_ptr<Framebuffer> G3D::RenderDevice::readFramebuffer ( ) const

inline

Returns the framebuffer currently bound for reading.

◆ renderMode()

RenderMode G3D::RenderDevice::renderMode ( ) const

◆ resetState()

void G3D::RenderDevice::resetState ( )

Sets all state to a clean rendering environment.

◆ screenshot()

String G3D::RenderDevice::screenshot ( const String & filepath = "./" ) const

Takes a JPG screenshot of the front buffer and saves it to a file.

Returns the name of the file that was written. Example: renderDevice->screenshot("screens/");

Pressing the "movie" icon in the GApp developer HUD or pressing F4 also allows direct screenshot capture.

◆ screenshotPic()

shared_ptr<Image> G3D::RenderDevice::screenshotPic	(	bool	getAlpha = `false`,
		bool	invertY = `true`
	)		const

Takes a screenshot.

Reads from the current read buffer; use setReadBuffer(RenderDevice::READ_FRONT) to explicitly read from the front buffer, which is substantially faster than reading from the back buffer.

Parameters

getAlpha	If true, the alpha channel of the frame buffer is also read back.
invertY	It is faster to read back images upside down because that is how OpenGL stores them. Set invertY=false for this fast but upsidedown result.

◆ sendIndices() [1/3]

template<class T >

void G3D::RenderDevice::sendIndices	(	PrimitiveType	primitive,
		int	numIndices,
		const T *	index
	)

inline

Draws the specified kind of primitive from the current vertex array.

Deprecated:: Use sendIndices(PrimitiveType, const AttributeArray&)

Referenced by sendIndices().

◆ sendIndices() [2/3]

void G3D::RenderDevice::sendIndices	(	PrimitiveType	primitive,
		const IndexStream &	indexStream
	)

Send indices from an index buffer stored inside a vertex buffer.

This is faster than sending from main memory on most GPUs.

◆ sendIndices() [3/3]

template<class T >

void G3D::RenderDevice::sendIndices	(	PrimitiveType	primitive,
		const Array< T > &	index
	)

inline

Draws the specified kind of primitive from the current vertex array.

Deprecated:: Use sendIndices(PrimitiveType, const AttributeArray&)

◆ sendIndicesInstanced()

void G3D::RenderDevice::sendIndicesInstanced	(	PrimitiveType	primitive,
		const IndexStream &	indexStream,
		int	numInstances
	)

Send indices from an index buffer stored inside a vertex buffer.

This is faster than sending from main memory on most GPUs.

Inside the vertex shader, gl_InstanceID is bound to the number of the instance. The first instance is 0, the last is numInstances - 1.

(Equivalent to glDrawElementsInstanced)

Parameters

numInstances number of instances of these indices to send

◆ sendMultidrawIndices()

void G3D::RenderDevice::sendMultidrawIndices	(	PrimitiveType	primitive,
		const Array< IndexStream > &	indexStreams,
		int	numInstances,
		bool	useInstances
	)

Draws the specified kind of primitive using each one of the indexStreams.

◆ sendMultidrawSequentialIndices()

void G3D::RenderDevice::sendMultidrawSequentialIndices	(	PrimitiveType	primitive,
		const Array< int > &	indexCounts,
		const Array< int > &	indexOffsets
	)

Draws the specified kind of primitive using sequential indices.

◆ sendSequentialIndices()

void G3D::RenderDevice::sendSequentialIndices	(	PrimitiveType	primitive,
		int	numVertices,
		int	startVertex = `0`
	)

Renders sequential vertices from the current vertex array.

(Equivalent to glDrawArrays)

◆ sendSequentialIndicesInstanced()

void G3D::RenderDevice::sendSequentialIndicesInstanced	(	PrimitiveType	primitive,
		int	numVertices,
		int	numInstances
	)

Renders sequential vertices from the current vertex array for multiple instances.

Inside the vertex shader, gl_InstanceID is bound to the number of the instance. The first instance is 0, the last is numInstances - 1.

(Equivalent to glDrawArraysInstanced)

Parameters

numInstances number of instances of these indices to send

◆ setAlphaTest()

void G3D::RenderDevice::setAlphaTest	(	AlphaTest	test,
		float	reference
	)

If the alpha test is ALPHA_CURRENT, the reference is ignored.

Illegal unless OSWindow::Settings::allowAlphaTest is true.

◆ setAlphaWrite()

void G3D::RenderDevice::setAlphaWrite ( bool b )

inline

The frame buffer may optionally have an alpha channel for each pixel, depending on how the G3D::OSWindow was initialized (see G3D::RenderDevice::init, and G3D::OSWindow::Settings).

When the alpha channel is present, rendering to the screen also renders to the alpha channel by default. Alpha writing is used for render-to-texture and deferred lighting effects.

Rendering to the alpha channel does not produce transparency effects–this is an alpha output, not an alpha input. See RenderDevice::setBlendFunc for a discussion of blending.

◆ setBlendFunc() [1/2]

void G3D::RenderDevice::setBlendFunc	(	Framebuffer::AttachmentPoint	buf,
		BlendFunc	srcRGB,
		BlendFunc	dstRGB,
		BlendEq	eqRGB = `BLENDEQ_ADD`,
		BlendFunc	srcA = `BLEND_SAME_AS_RGB`,
		BlendFunc	dstA = `BLEND_SAME_AS_RGB`,
		BlendEq	eqA = `BLENDEQ_SAME_AS_RGB`
	)

Equivalent to glBlendFunc and glBlendEquation.

Use setBlendFunc(Framebuffer::COLOR0, RenderDevice::BLEND_ONE, RenderDevice::BLEND_ZERO, RenderDevice::BLENDEQ_ADD) to shut off blending.

Use setBlendFunc(Framebuffer::COLOR0, RenderDevice::BLEND_SRC_ALPHA, RenderDevice::BLEND_ONE_MINUS_SRC_ALPHA, RenderDevice::BLENDEQ_ADD) for unmultiplied alpha blending and setBlendFunc(Framebuffer::COLOR0, RenderDevice::BLEND_ONE, RenderDevice::BLEND_ONE_MINUS_SRC_ALPHA, RenderDevice::BLENDEQ_ADD) for premultiplied alpha.

Draw your objects from back to front, objects with alpha last. Objects with alpha only get drawn properly if the things they're occluding have been drawn before the alpha'd objects.

Generally, turn alpha on, draw your alpha-blended things, then turn alpha off. Separate functions can be passed for RGB and Alpha channels: for example, by default, eqA is BLENDEQ_SAME_AS_RGB: this will force eqA to be the same function as eqRGB during this call. This interacts with BLEND_EQ current in the following way: If eqRGB = BLENDEQ_CURRENT and eqA = BLENDEQ_SAME_AS_RGB, then eqA will be equal to the current m_state.blendEqRGB,NOT the current m_state.blendEqA

◆ setBlendFunc() [2/2]

void G3D::RenderDevice::setBlendFunc	(	BlendFunc	src,
		BlendFunc	dst,
		BlendEq	eqRGB = `BLENDEQ_ADD`,
		BlendEq	eqA = `BLENDEQ_SAME_AS_RGB`,
		Framebuffer::AttachmentPoint	buf = `Framebuffer::COLOR0`
	)

Deprecated:: overload for backwards compatability, use version above instead

◆ setCameraToWorldMatrix()

void G3D::RenderDevice::setCameraToWorldMatrix ( const CoordinateFrame & cFrame )

See RenderDevice::setObjectToWorldMatrix.

◆ setClip2D()

void G3D::RenderDevice::setClip2D ( const Rect2D & clip )

Sets a 2D clipping region (OpenGL scissor region) relative to the current window dimensions (not the viewport).

Prevents rendering outside the clip region.

Pushing a new Framebuffer (but not setting one explicitly) resets the clip2D state to the ful screen.

Set to Rect2D::inf() to disable. Default is disabled.

Note that the clip uses G3D 2D coordinates, where the upper-left of the window is (0, 0).

See also: setGuardBandClip2D, intersectClip2D, clip2D

Referenced by intersectClip2D(), and setGuardBandClip2D().

◆ setColorClearValue()

void G3D::RenderDevice::setColorClearValue ( const Color4 & c )

◆ setColorWrite()

void G3D::RenderDevice::setColorWrite ( bool b )

inline

Color writing is on by default.

Disabling color write allows a program to render to the depth and stencil buffers without creating a visible image in the frame buffer.
This is useful for occlusion culling, shadow rendering, and some computational solid geometry algorithms.
Rendering may be significantly accelerated when color write is disabled.

◆ setCullFace()

void G3D::RenderDevice::setCullFace ( CullFace f )

Equivalent to glCullFace.

RenderDevice will internally swap the OpenGL cull direction when rendering to a Framebuffer in order to be consistent with the inverted Y axis.

◆ setDebugOutput()

void G3D::RenderDevice::setDebugOutput ( bool b )

Set OSWindow::Settings::debugContext = true and then set this to true to enable OpenGL debugging output.

◆ setDepthClearValue()

void G3D::RenderDevice::setDepthClearValue ( float d )

◆ setDepthRange()

void G3D::RenderDevice::setDepthRange	(	float	low,
		float	high
	)

inline

◆ setDepthTest()

void G3D::RenderDevice::setDepthTest ( DepthTest test )

Use ALWAYS_PASS to shut off testing.

Referenced by setDepthWrite().

◆ setDepthWrite()

void G3D::RenderDevice::setDepthWrite ( bool b )

inline

Defaults to true.

◆ setDrawBuffer()

void G3D::RenderDevice::setDrawBuffer ( DrawBuffer drawBuffer )

Sets the frame buffer that is written to.

Used to intentionally draw to the front buffer and for stereo rendering. Its operation is sensitive to the current framebuffer being written to. If the framebuffer is the primary display then only visible buffers may be specified. If framebuffer() is non-nullptr then the drawBuffer is stored for later use but the actual draw buffers remain the ones specified by the framebuffer.

When using a G3D::Framebuffer it is not necessary to explicitly set the draw buffer; that is handled automatically by beforePrimitive().

◆ setDrawFramebuffer()

void G3D::RenderDevice::setDrawFramebuffer ( const shared_ptr< Framebuffer > & fbo )

Sets the framebuffer to render to.

Use nullptr to set the desired rendering target to the windowing system display.

Note that if the new framebuffer has different dimensions than the current one the projectionMatrix and viewport will likely be incorrect. Call RenderDevice::setProjectionAndCamera matrix again to update them.

See RenderDevice::pushState and push2D for a way to set the frame buffer and viewport simultaneously.

Parameters

fbo	Framebuffer to render to.

Referenced by setFramebuffer().

◆ setFramebuffer()

void G3D::RenderDevice::setFramebuffer ( const shared_ptr< Framebuffer > & fb )

inline

Sets both the draw and read framebuffers.

◆ setGuardBandClip2D()

void G3D::RenderDevice::setGuardBandClip2D ( const Vector2int16 thickness )

inline

Sets a clip2D region that is inset from the current framebuffer's boundaries by thickness.

◆ setInvertY()

void G3D::RenderDevice::setInvertY ( bool i )

inline

Override the invertY() flag, which is normally set automatically by calls to setFramebuffer.

◆ setLogicOp()

void G3D::RenderDevice::setLogicOp ( const LogicOp op )

Equivalent to glLogicOp call.

◆ setObjectToWorldMatrix()

void G3D::RenderDevice::setObjectToWorldMatrix ( const CoordinateFrame & cFrame )

This is not the OpenGL MODELVIEW matrix: it is a matrix that maps object space to world space.

The actual MODELVIEW matrix is cameraToWorld.inverse() * objectToWorld. You can retrieve it with getModelViewMatrix.

◆ setPointSize()

void G3D::RenderDevice::setPointSize ( float diameter )

Equivalent to glPointSize.

◆ setPolygonOffset()

void G3D::RenderDevice::setPolygonOffset ( float offset )

Equivalent to glPolygonOffset

◆ setProjectionAndCameraMatrix()

void G3D::RenderDevice::setProjectionAndCameraMatrix	(	const Projection &	p,
		const CFrame &	c
	)

Setting both simultaneously minimizes OpenGL state changes.

◆ setProjectionMatrix() [1/2]

void G3D::RenderDevice::setProjectionMatrix ( const Matrix4 & P )

To set a typical 3D perspective matrix, use either.

renderDevice->setProjectionMatrix(Matrix4::perspectiveProjection(...))

or call setProjectionAndCameraMatrix.

◆ setProjectionMatrix() [2/2]

void G3D::RenderDevice::setProjectionMatrix ( const class Projection & P )

◆ setReadBuffer()

void G3D::RenderDevice::setReadBuffer ( ReadBuffer readBuffer )

◆ setReadFramebuffer()

void G3D::RenderDevice::setReadFramebuffer ( const shared_ptr< Framebuffer > & fbo )

Referenced by setFramebuffer().

◆ setRenderMode()

void G3D::RenderDevice::setRenderMode ( RenderMode mode )

◆ setSRGBConversion()

void G3D::RenderDevice::setSRGBConversion ( bool b )

By default, opengl does not covert writes to an sRGB texture into sRGB color space.

Set this to true to force such a conversion.

◆ setStencilClearValue()

void G3D::RenderDevice::setStencilClearValue ( int s )

◆ setStencilConstant()

void G3D::RenderDevice::setStencilConstant ( int reference )

Sets the constant used in the stencil test and operation (if op == STENCIL_REPLACE)

◆ setStencilOp() [1/2]

void G3D::RenderDevice::setStencilOp	(	StencilOp	fail,
		StencilOp	zfail,
		StencilOp	zpass
	)

If wrapping is not supported on the device, the nearest mode is selected.

Unlike OpenGL, stencil writing and testing are independent. You do not need to enable the stencil test to use the stencil op.

Use KEEP, KEEP, KEEP to disable stencil writing. Equivalent to a combination of glStencilTest, glStencilFunc, and glStencilOp.

If there is no depth buffer, the depth test always passes. If there is no stencil buffer, the stencil test always passes.

◆ setStencilOp() [2/2]

void G3D::RenderDevice::setStencilOp	(	StencilOp	frontStencilFail,
		StencilOp	frontZFail,
		StencilOp	frontZPass,
		StencilOp	backStencilFail,
		StencilOp	backZFail,
		StencilOp	backZPass
	)

When GLCaps::GL_ARB_stencil_two_side is true, separate stencil operations can be used for front and back faces.

This is useful for rendering shadow volumes.

◆ setStencilTest()

void G3D::RenderDevice::setStencilTest ( StencilTest test )

◆ setSwapBuffersAutomatically()

void G3D::RenderDevice::setSwapBuffersAutomatically ( bool b )

By default, OSWindow::swapGLBuffers is invoked automatically between RenderDevice::endFrame and the following RenderDevice::beginFrame to update the front buffer (what the user sees) from the back buffer (where rendering commands occur).

You may want to suppress this behavior, for example, in order to render to the back buffer and capture the result in a texture.

The state of swapBuffersAutomatically is not stored by RenderDevice::pushState because it is usually invoked outside of RenderDevice::beginFrame / endFrame.

◆ setVertexAttribArray()

void G3D::RenderDevice::setVertexAttribArray	(	unsigned int	attribNum,
		const class AttributeArray &	v
	)

Vertex attributes are a generalization of the various per-vertex attributes that relaxes the format restrictions.

There are at least 16 attributes on any card (some allow more). During the days of fixed-function, these attributes had special meaning, but G3D no longer supports the fixed function pipeline.

◆ setViewport()

void G3D::RenderDevice::setViewport ( const Rect2D & v )

(0, 0) is the upper-left corner of the screen.

◆ setWindow()

void G3D::RenderDevice::setWindow ( OSWindow * window )

Sets the OSWindow used by this RenderDevice.

Useful if using a single RenderDevice for multiple windows

◆ shadeMode()

ShadeMode G3D::RenderDevice::shadeMode ( ) const

inline

◆ sRGBConversion()

bool G3D::RenderDevice::sRGBConversion ( ) const

inline

◆ stats()

const Stats& G3D::RenderDevice::stats ( )

inline

◆ stencilTest()

StencilTest G3D::RenderDevice::stencilTest ( ) const

◆ swapBuffers()

void G3D::RenderDevice::swapBuffers ( )

Manually swap the front and back buffers.

Using swapBuffersAutomatically() is recommended instead of manually swapping because it has higher performance.

◆ swapBuffersAutomatically()

bool G3D::RenderDevice::swapBuffersAutomatically ( ) const

inline

◆ swapBufferTimer()

const Stopwatch& G3D::RenderDevice::swapBufferTimer ( ) const

inline

Measures the amount of time spent in swapBuffers.

If high, indicates that the CPU and GPU are not working in parallel

◆ unsetVertexAttribArray()

void G3D::RenderDevice::unsetVertexAttribArray ( unsigned int attribNum )

Counterpart to setVertexAttribArray.

◆ viewport()

const Rect2D& G3D::RenderDevice::viewport ( ) const

◆ width()

int G3D::RenderDevice::width ( ) const

Pixel dimensions of the OpenGL window interior

Referenced by setGuardBandClip2D().

◆ window()

OSWindow* G3D::RenderDevice::window ( ) const

Returns the OSWindow used by this RenderDevice.

◆ worldToCameraMatrix()

const CoordinateFrame& G3D::RenderDevice::worldToCameraMatrix ( ) const

Friends And Related Function Documentation

◆ AttributeArray

friend class AttributeArray

friend

◆ Framebuffer

friend class Framebuffer

friend

◆ Milestone

friend class Milestone

friend

◆ UserInput

friend class UserInput

friend

◆ VertexBuffer

friend class VertexBuffer

friend

Member Data Documentation

◆ current

thread_local RenderDevice* G3D::RenderDevice::current

static

RenderDevice active on this thread, nullptr if there is not one.

By default, G3D creates a single RenderDevice on the main thread. If you create a second OpenGL context you should also make a RenderDevice for it .

◆ m_lastTime

RealTime G3D::RenderDevice::m_lastTime

protected

Time at which the previous endFrame() was called.

◆ m_previousFrameStats

Stats G3D::RenderDevice::m_previousFrameStats

protected

Latched in swapbufers.

Referenced by stats().

◆ m_stats

Stats G3D::RenderDevice::m_stats

protected

Referenced by majGLStateChange(), majStateChange(), minGLStateChange(), and minStateChange().

◆ m_swapTimer

Stopwatch G3D::RenderDevice::m_swapTimer

protected

Times swapBuffers.

Referenced by swapBufferTimer().

◆ m_tempVAR

Array<AttributeArray> G3D::RenderDevice::m_tempVAR

protected

Storage for setVARs.

Cleared by endIndexedPrimitives.

◆ m_varState

VARState G3D::RenderDevice::m_varState

protected

Note: note backed up by push/pop, since push/pop can't be called inside indexed primitives.

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

◆ anonymous enum

◆ anonymous enum

◆ AlphaTest

◆ BlendEq

◆ BlendFunc

◆ DepthTest

◆ DrawBuffer

◆ LogicOp

◆ ReadBuffer

◆ RenderMode

◆ ShadeMode

◆ StencilOp

◆ StencilTest

Constructor & Destructor Documentation

◆ RenderDevice()

◆ ~RenderDevice()

Member Function Documentation

◆ afterPrimitive()

◆ alphaTest()

◆ alphaTestReference()

◆ alphaWrite()

◆ apply() [1/2]

◆ apply() [2/2]

◆ beforePrimitive()

◆ beginFrame()

◆ beginIndexedPrimitives()

◆ beginOpenGL()

◆ cameraToWorldMatrix()

◆ cleanup()

◆ clear() [1/2]

◆ clear() [2/2]

◆ clearFramebuffer()

◆ clip2D()

◆ colorFormat()

◆ colorWrite()

◆ copyTextureFromScreen()

◆ cullFace()

◆ currentDrawFramebufferComplete()

◆ currentReadFramebufferComplete()

◆ depthWrite()

◆ describeSystem() [1/2]

◆ describeSystem() [2/2]

◆ drawBuffer()

◆ drawFramebuffer()

◆ endFrame()

◆ endIndexedPrimitives()

◆ endOpenGL()

◆ framebuffer()

◆ getBlendFunc()

◆ getCardDescription()

◆ getDepthBufferValue()

◆ getWindowHDC()

◆ height()

◆ init() [1/2]

◆ init() [2/2]

◆ initialized()

◆ intersectClip2D()

◆ invertY()

◆ invertYMatrix()

◆ issueMemoryBarrier()

◆ majGLStateChange()

◆ majStateChange()

◆ minGLStateChange()

◆ minStateChange()

◆ modelViewMatrix()

◆ modelViewProjectionMatrix()

◆ modifyArgsForRectModeApply()

◆ objectToScreenMatrix()

◆ objectToWorldMatrix()

◆ pop2D()

◆ popState()