G3D::Film Class Reference

Post processing: gamma correction, exposure, bloom, and screen-space antialiasing. More...

Inherits G3D::ReferenceCountedObject.

Public Types
typedef shared_ptr< class Film >	Ref

Public Member Functions
void	exposeAndRender (RenderDevice *rd, const FilmSettings &settings, const shared_ptr< Texture > &input, int downsample=1)
	Renders the input as filtered by the film settings to the currently bound framebuffer.
void	exposeAndRender (RenderDevice *rd, const FilmSettings &settings, const shared_ptr< Texture > &input, shared_ptr< Texture > &output, int downsample=1)
	Render to texture helper.

Static Public Member Functions
static Ref	create (const ImageFormat *intermediateFormat=ImageFormat::RGB16F(), const ImageFormat *targetFormat=ImageFormat::RGB8())
	Create a new Film instance.

Detailed Description

Post processing: gamma correction, exposure, bloom, and screen-space antialiasing.

Computer displays are not capable of representing the range of values that are rendered by a physically based system. For example, the brightest point on a monitor rarely has the intensity of a light bulb. Furthermore, for historical (and 2D GUI rendering) reasons, monitors apply a power ("gamma") curve to values. So rendering code that directly displays radiance values on a monitor will neither capture the desired tonal range nor even present the values scaled linearly. The Film class corrects for this using the simple tone mapping algorithm presented in Pharr and Humphreys 2004 extended with color desaturation.

To use, render to a G3D::Texture using G3D::Framebuffer, then pass that texture to exposeAndDraw() to produce the final image for print or display on screen. For example, on initialization, perform:

 film = Film::create();
 fb = Framebuffer::create("Offscreen");
 colorBuffer = Texture::createEmpty("Color", renderDevice->width(), renderDevice->height(), ImageFormat::RGB16F(), Texture::DIM_2D_NPOT, Texture::Settings::video());
 fb->set(Framebuffer::COLOR_ATTACHMENT0, colorBuffer);
 fb->set(Framebuffer::DEPTH_ATTACHMENT, 
     Texture::createEmpty("Depth", renderDevice->width(), renderDevice->height(), ImageFormat::DEPTH24(), Texture::DIM_2D_NPOT, Texture::Settings::video()));

and then per frame,

 rd->pushState(fb);
     ...Rendering code here...
 rd->popState(); 
 film->exposeAndRender(rd, colorBuffer);

The bloom effects are most pronounced when rendering values that are actually proportional to radiance. That is, if all of the values in the input are on a narrow range, there will be little bloom. But if the sky, highlights, emissive surfaces, and light sources are 10x brighter than most scene objects, they will produce attractive glows and halos.

When rendering multiple viewports or off-screen images, use a separate Film instance for each size of input for maximum performance.

Requires shaders.

Member Typedef Documentation

typedef shared_ptr<class Film> G3D::Film::Ref

Member Function Documentation

static Ref G3D::Film::create ( const ImageFormat *  intermediateFormat = ImageFormat::RGB16F(), const ImageFormat *  targetFormat = ImageFormat::RGB8()  )

static

Create a new Film instance.

Parameters

intermediateFormat	Intermediate precision to use when processing images during bloom. This should usually match your source format. Defaults to ImageFormat::RGB16F. A floating-point texture is used in case values are not on the range (0, 1). If you know that your data is on a smaller range, try ImageFormat::RGB8() or ImageFormat::RGB10A2() for increased space savings or performance.
targetFormat	Intermediate precision used when processing images after bloom, during antialiasing. This should usually match your destination format. Defaults ot ImageFormat::RGB8().

void G3D::Film::exposeAndRender	(	RenderDevice *	rd,
		const FilmSettings &	settings,
		const shared_ptr< Texture > &	input,
		int	downsample = 1
	)

Renders the input as filtered by the film settings to the currently bound framebuffer.

Parameters

downsample

One side of the downsampling filter in pixels. 1 = no downsampling. 2 = 2x2 downsampling (antialiasing). Not implemented.

If rendering to a bound texture, set the Texture::Visualization::documentGamma = gamma() afterwards.

void G3D::Film::exposeAndRender	(	RenderDevice *	rd,
		const FilmSettings &	settings,
		const shared_ptr< Texture > &	input,
		shared_ptr< Texture > &	output,
		int	downsample = 1
	)

Render to texture helper.

You can also render to a texture by binding output to a FrameBuffer, setting the FrameBuffer on the RenderDevice, and calling the three-argument version of exposeAndRender. That process will be faster than this version, which must create its FrameBuffer every time it is invoked.

Parameters

output

If NULL, this will be allocated to be the same size and format as input.