Provides a built-in mechanism to render to Texture or Cubemap. FrameBuffer creates an offscreen back buffer and allows you to draw directly to one or multiple render target. These targets (or attachments) can either be used to store colors, depth or stencil data and can be used for multiple different purposes such as reflection, deferred rendering and other post-processing effects.

It is a very powerful tool that allows you to store and process the result multi-pass rendering to different storage and process them in Shader.

See Also

Camera, Texture, Cubemap, Texmap

Static Variables

Name	Description
`camera`	Parent Camera where the FrameBuffer is attached.
Declaration Camera *camera
`size`	The size of the FrameBuffer either in pixels or specified as viewport ratio.
Declaration vec2 size
`absolute`	Specify if the FrameBuffer `size` should be absolute or relative.
Declaration bool absolute
`width`	The current FrameBuffer width in pixels.
Declaration unsigned short width
`height`	The current FrameBuffer height in pixels.
Declaration unsigned short height
`framebuffer_id`	Internal GPU FrameBuffer id.
Declaration unsigned int framebuffer_id Remarks A value different than `0` represent that the FrameBuffer have been created and ready to use for blitting operations etc...
`colorbuffer_id`	Internal GPU id of the color buffer associated to the active FrameBuffer.
Declaration unsigned int colorbuffer_id Note Only a non zero value if the FrameBuffer have been initalized with `color_buffer` set to `true` and no color attachment is present.
`depthbuffer_id`	Internal GPU id of the depth buffer associated to the active FrameBuffer.
Declaration unsigned int depthbuffer_id Note Only a non zero value if the FrameBuffer have been initalized with `depth_buffer` set to `true` and no depth attachment have been provided.
`stencilbuffer_id`	Internal GPU id of the depth/stencil buffer associated to the active FrameBuffer.
Declaration unsigned int stencilbuffer_id Note Only a non zero value if the FrameBuffer have been initalized with `depth_buffer` and `stencil_buffer` set to `true` and no depth/stencil attachment is provided.

Variables

Name	Description
`redraw`	Draw another FrameBuffer pass.
Declaration bool redraw
`update`	Force the FrameBuffer to be updated next time it is required by the drawing sequence.
Declaration bool update
`color_buffer`	Specify wether or not the FrameBuffer requires a color buffer to be created.
Declaration bool color_buffer Note This setting will get overridden if a color attachment is connected to the FrameBuffer.
`depth_buffer`	Specify wether or not the FrameBuffer requires a depth buffer to be created.
Declaration bool depth_buffer Note This setting will get overridden if a depth attachment is connected to the FrameBuffer.
`stencil_buffer`	Specify wether or not the FrameBuffer requires a stencil buffer to be created.
Declaration bool stencil_buffer Note This setting will get overridden if a depth/stencil attachment is connected to the FrameBuffer.

Functions

Name	Description
`Clear`	Reset the FrameBuffer and flag it for update.
Declaration void Clear( void )
`SetSize`	Adjust the dimensions of the active FrameBuffer.
Declaration void SetSize( float size_x, float size_y, bool absolute ) Parameters `size_x`: Size of the FrameBuffer on the `X` axis. `size_y`: Size of the FrameBuffer on the `Y` axis. `absolute`: Specify if the size `XY` are absolute or relative values. Note If the `absolute` parameter is `true` the size `XY` will be expected to be in pixels; else has a relative viewport ratio (ie: 0.5 = 50% of the current viewport dimensions).
`SetStorage`	Specify the type of storage the FrameBuffer should support; and trigger an internal update.
Declaration void SetStorage( bool color_buffer, bool depth_buffer, bool stencil_buffer ) Parameters `color_buffer`: Force a default color buffer to be created. `depth_buffer`: Force the FrameBuffer to have a depth buffer. `stencil_buffer`: Force the FrameBuffer to create a stencil buffer.
`SetColorTexture`	Attach or detach an existing Texture as color buffer.
Declaration bool SetColorTexture( const unsigned char index, Texture color_attachment, const unsigned short layer ) Parameters* `index`: Slot index where to place the Texture. `color_attachment`: Reference to an existing Texture suitable to be a color attachment. Pass `nil` to disconnect any existing reference to the slot. `layer`: The slice of the texture 3d or the texture 2d array to render to. Return Value `true` if the Texture reference have been connected to the slot index specified. Return `false` if the slot index is invalid (above the color attachment limits), if the Texture is a 3d texture, if the FrameBuffer is set to draw to a Cubemap or if the Texture is not a valid format (different from `R`,`RG`, `RGB` or `RGBA`).
`SetColorCubemap`	Attach or detach a Cubemap as color buffer.
Declaration bool SetColorCubemap( const unsigned char index, Cubemap color_attachment ) Parameters* `index`: Slot index where to place the Cubemap. `color_attachment`: Reference to an existing Cubemap suitable to be a color attachment. Pass `nil` to disconnect any existing Cubemap reference to the slot. Return Value `true` if the Texture reference have been connected to the slot index specified. Return `false` if the FrameBuffer is not setup to render to a Cubemap; if UsageType of the Cubemap is not `kDynamic` or the format of the `color_attachment` is invalid (only R, RG, RGB and RGBA are accepted).
`SetColorDiscard`	Provides an opportunity for driver optimization by invalidating the content of the FrameBuffer.
Declaration bool SetColorDiscard( const unsigned char index, bool discard ) Parameters `index`: Specify the slot index to be discarded. `discard`: Force the content of the color attachment to be discarded. Return Value `true` if the slot index provided is valid; else return `false`.
`IsColorDiscard`	Helper to verify if a specific color slot is marked to be discarded.
Declaration bool IsColorDiscard( const unsigned char index ) Parameters `index`: Color attachment slot index to validate if it is marked to be discarded. Return Value `true` if the slot index provided is valid and marked to be discarded; else return `false`.
`SetColorReadPixels`	Force the FrameBuffer content to be transferred to the Texmap of the Texture or Cubemap used.
Declaration bool SetColorReadPixels( const unsigned char index, bool read_pixels ) Parameters `index`: The index of the slot you wish to transfer the texel data. `read_pixels`: Determine wether or not the texel data should be transferred from GPU to CPU memory. Return Value `true` if the slot index in valid; `false` if the index is incorrect or above the driver limits.
`IsColorReadPixels`	Helper to check if a specific slot is marked to transfer texel data.
Declaration bool IsColorReadPixels( const unsigned char index ) Parameters `index`: Slot index to check if it is marked or not for texel transfer. Return Value `true` if the slot index provided is valid and marked for transfer; else return `false`.
`SetDepthTexture`	Connect a depth attachment to the active FrameBuffer.
Declaration bool SetDepthTexture( Texture depth_attachment, const unsigned short layer ) Parameters* `depth_attachment`: A valid reference to a Texture that is set to hold depth values. Pass `nil` to disconnect any reference to the slot. `layer`: The slice of the texture 3d or the texture 2d array to render to. Return Value `true` on success; `false` if the FrameBuffer is set up to render to Cubemap, if the `depth_attachment` is invalid (not a depth or a 3d Texture) or if the TextureType is not set to `kAttachment`.
`SetDepthCubemap`	Connect a depth Cubemap attachment to the active FrameBuffer.
Declaration bool SetDepthCubemap( Cubemap depth_attachment ) Parameters* `depth_attachment`: A valid reference to a Cubemap that is set to hold depth values. Pass `nil` to disconnect any reference to the slot. Return Value `true` on success; `false` if the FrameBuffer is not setup to render to a Cubemap, if the `depth_attachment` is invalid (not setup for depth) or if the Cubemap UsageType is not `kDynamic`.
`SetDepthDiscard`	Provides an opportunity for driver optimization by invalidating the content of the FrameBuffer.
Declaration bool SetDepthDiscard( const unsigned char index, bool discard ) Parameters `index`: Specify the slot index to be discarded. `discard`: Force the content of the depth attachment to be discarded. Return Value `true` if the slot index provided is valid; else return `false`.
`IsDepthDiscard`	Helper to verify if a specific depth slot is marked to be discarded.
Declaration bool IsDepthDiscard( const unsigned char index ) Parameters `index`: Depth attachment slot index to validate if it is marked to be discarded. Return Value `true` if the slot index provided is valid and marked to be discarded; else return `false`.
`BlitBegin`	Prepare the active FrameBuffer for a blit operation.
Declaration bool BlitBegin( void ) Return Value `true` if the FrameBuffer have been created and is ready to blit; `false` if no `framebuffer_id` have been generated.
`Blit`	Copy the content of a FrameBuffer to the active FrameBuffer.
Declaration bool Blit( FrameBuffer src, const ClearBuffer mask, const unsigned char src_index, const unsigned char dst_index, bool linear ) Parameters* `src`: Reference to the source FrameBuffer; to directly copy the content of the default back buffer pass `nil`. `mask`: Bit mask of ClearBuffer value(s) specifying what content to copy. `src_index`: Source color attachment index (only apply when using `fColorBufferBit`). `dst_index`: Destination color attachment index (only apply when using `fColorBufferBit`). `linear`: Force to use linear interpolation while copying the content. Return Value `true` on success; `false` if the active FrameBuffer have not yet being created, or if no `mask` have been provided.
`BlitEnd`	Restore the previouse draw buffers associated the active FrameBuffer and terminate the blit operation.
Declaration bool BlitEnd( void )
`GetColorTexture`	Retrieve a Texture color attachment connected to a specific slot index.
Declaration Texture GetColorTexture( const unsigned char index ) Parameters* `index`: Index of the slot to retrieve the color attachment for. Return Value A Texture reference or `nil` if the slot index is invalid or no attachment is connected to the slot.
`GetColorCubemap`	Retrieve a Cubemap color attachment connected to a specific slot index.
Declaration Texture GetColorCubemap( const unsigned char index ) Parameters* `index`: Index of the slot to retrieve the color attachment for. Return Value A Cubemap reference or `nil` if the slot index is invalid or no attachment is connected to the slot.
`GetDepthTexture`	Retrieve a Texture depth attachment connected to a specific slot index.
Declaration Texture GetDepthTexture( const unsigned char index ) Parameters* `index`: Index of the slot to retrieve the depth attachment for. Return Value A Texture reference or `nil` if the slot index is invalid or no attachment is connected to the slot.
`GetDepthCubemap`	Retrieve a Cubemap depth attachment connected to a specific slot index.
Declaration Texture GetDepthCubemap( const unsigned char index ) Parameters* `index`: Index of the slot to retrieve the depth attachment for. Return Value A Cubemap reference or `nil` if the slot index is invalid or no attachment is connected to the slot.
`GetColorTextureLayer`	Retrieve the current layer use by a specific color texture slot.
Declaration int GetColorTextureLayer( const unsigned char index ) Parameters `index`: Index of the slot to retrieve the active layer. Return Value `-1` if the active slot pointed by `index` if not a texture3d or a sampler2DArray; else return the active layer used by the slot index.
`GetDepthTextureLayer`	Retrieve a Cubemap depth attachment connected to a specific slot index.
Declaration int GetDepthTextureLayer( void ) Parameters `index`: Index of the slot to retrieve the depth attachment for. Return Value Returns `-1` if the depth/stencil attachment is not a if not a texture3d or a sampler2DArray; else return the active slice used by the slot.
`Rebuild`	Force the active FrameBuffer to be rebuilt.
Declaration void Rebuild( void )
`Discard`	Hint the driver to discard (when possible) from memory the content of the active FrameBuffer.
Declaration void Rebuild( void )

UsageType

Constant values used by diverse classes to determine data usage.

kStatic: The data is stored locally and is read-only and cannot be changed.
kDynamic: Data are generated dynamically and can be changed either automatically by the system or manually by the user.
kExternal: Data is stored externally and can only be read.

FaceType

Static enumerators used to determine the face of a Cubemap

kPositiveX: Positive X axis.
kNegativeX: Negative X axis.
kPositiveY: Positive Y axis.
kNegativeY: Positive Y axis.
kPositiveZ: Positive Z axis.
kNegativeZ: Positive Z axis.