Buffers

From Leadwerks Developer Wiki

Contents 1 Introduction 2 Tutorials 3 Commands 3.1 Creation & Destruction 3.1.1 CreateBuffer 3.1.2 CreateCustomBuffer 3.1.3 CopyBuffer 3.1.4 FreeBuffer 3.2 Modification 3.2.1 ClearBuffer 3.2.2 SetColorBuffer 3.2.3 SetDepthBuffer 3.2.4 SetNormalBuffer 3.3 Get Information 3.3.1 GetColorBuffer 3.3.2 GetDepthBuffer 3.3.3 BufferWidth 3.3.4 BufferHeight 3.4 Global Commands 3.4.1 SetBuffer 3.4.2 SaveBuffer 3.4.3 BackBuffer 3.4.4 CurrentBuffer 3.5 Capabilities Commands 3.5.1 MaxColorBuffers

Introduction

Render buffers are a powerful part of the Leadwerks Engine 2 renderer. Rendering is always performed on a buffer. This can take the form of a texture-based buffer with optional color, depth, and normal components, a custom buffer the user creates and manages, or the graphics window back buffer. Texture-based buffers can be drawn onto other buffers to perform post-processing effects like bloom and depth-of-field. Texture-based buffers can also be used as textures and applied to materials. This technique can be used to render reflections, or a closed-circuit camera system.

Tutorials

• Rendering Lights
• Post-Processing Effects

Commands

Creation & Destruction

CreateBuffer

• C: TBuffer CreateBuffer(int width=640, int height=480, int flags=BUFFER_COLOR
• C++:
  
  • virtual void Buffer::Create( int width, int height, int flags = BUFFER_COLOR
• BlitzMax: CreateBuffer:TBuffer( width:Int, height:Int, flags:Int )
• Pascal: function CreateBuffer ( width:Integer=640; height:Integer=480; flags:Integer=BUFFER_COLOR or BUFFER_DEPTH ): THandle;

Creates a new buffer with the specified parameters. Flags:

• BUFFER_DEPTH
• BUFFER_NORMAL (= BUFFER_COLOR1)
• BUFFER_COLOR, BUFFER_COLOR0
• BUFFER_COLOR1
• BUFFER_COLOR2
• BUFFER_COLOR3

This command increments the object reference count. To allow memory management to delete the resource, the reference count must be decremented by calling Release(object).

[Examples]

CreateCustomBuffer

• C: TBuffer CreateCustomBuffer( byte* getsize, byte* makecurrent)
• C++: virtual void Buffer::CreateCustom( byte* getsize, byte* makecurrent)
• Pascal: function CreateCustomBuffer ( GetSize:Pointer; MakeCurrent:Pointer ): THandle;

Creates and returns a new custom buffer. GetSize (defined as void _stdcall GetSize(int* width, int* height)) and MakeCurrent (defined as void _stdcall MakeCurrent(void)) are callback functions for the buffer. GetSize should return (by changing the value provided with a pointer) the size of the custum OpenGL buffer/context used. MakeCurrent should set the custom buffer as the current OpenGL context.

Note: CreateCustomBuffer can vary based on which language you use. CustomBuffers must be managed by the user. Leadwerks will only handle rendering to that buffer.

See here for an example (C/C++).

[Examples]

CopyBuffer

• C: TBuffer CopyBuffer( TBuffer source, int components )
• C++: void Buffer::Copy( Buffer& destination, int components ) const
• BlitzMax: CopyBuffer(src:TBuffer,dest:TBuffer,components:Int)
• Pascal: procedure CopyBuffer ( src:THandle; dst:THandle; components:Integer );

Copies buffer content to another buffer. The components can be any combination of the following:

• BUFFER_DEPTH
• BUFFER_NORMAL
• BUFFER_COLOR, BUFFER_COLOR0
• BUFFER_COLOR1
• BUFFER_COLOR2

[Examples]

FreeBuffer

• C: void FreeBuffer( TBuffer buffer )
• C++: void Buffer::Free( void ) Note: Also called from destructor
• BlitzMax: n/a
• Pascal: procedure FreeBuffer ( buffer:THandle );

Frees the specified buffer from memory.

[Examples]

Modification

ClearBuffer

• C: void ClearBuffer( int components=BUFFER_COLOR
• C++: void Buffer::Clear( int components=BUFFER_DEPTH
• BlitzMax: ClearBuffer( components:Int=BUFFER_DEPTH
• Pascal: procedure ClearBuffer ( components:Integer=BUFFER_DEPTH or BUFFER_COLOR );

Clears the current buffer. The components can be any combination of the following:

• BUFFER_DEPTH
• BUFFER_NORMAL
• BUFFER_COLOR, BUFFER_COLOR0
• BUFFER_COLOR1
• BUFFER_COLOR2

[Examples]

SetColorBuffer

• C: int SetColorBuffer(TBuffer buffer, TTexture texture, int index=0, int cubeface=0)
• C++: int Buffer::SetColor( const Texture& texture, int index, int cubeface )
• BlitzMax: SetColorBuffer:Int( buffer:TBuffer, texture:TTexture,index:Int, cubeface:Int )

Assigns a texture to one of the buffer's color channels. The optional cubeface parameter can be used to assign a cubemap face to a buffer.

[Examples]

SetDepthBuffer

• C: void SetDepthBuffer(TBuffer buffer, TTexture texture)
• C++: void Buffer::SetDepth( const Texture& texture )
• BlitzMax: SetDepthBuffer(buffer:TBuffer,texture:TTexture)
• Pascal: procedure SetDepthBuffer ( buffer:THandle; texture:THandle );

Assigns a texture to the buffer's depth channel.

[Examples]

SetNormalBuffer

• C: void SetNormalBuffer(TBuffer buffer, TTexture texture)
• C++: void Buffer::SetNormal( const Texture& texture )
• BlitzMax: SetNormalBuffer(buffer:TBuffer,texture:TTexture)
• Pascal: procedure SetNormalBuffer ( buffer:THandle; texture:THandle );

Assigns a texture to the buffer's normal channel.

[Examples]

Get Information

GetColorBuffer

• C: TTexture GetColorBuffer( TBuffer buffer, int index=0 )
• C++: Texture Buffer::GetColor( int index ) const
• BlitzMax: GetColorBuffer:TTexture( buffer:TBuffer, index:Int )
• Pascal: function GetColorBuffer ( buffer:THandle; n:Integer=0 ): THandle;

Returns the specified buffer's color texture (as a reference). Index is a number from one to MaxColorBuffers() minus 1.

[Examples]

GetDepthBuffer

• C: TTexture GetDepthBuffer( TBuffer buffer )
• C++: Texture Buffer::GetDepth( void ) const
• BlitzMax: GetDepthBuffer:TTexture( buffer:TBuffer )
• Pascal: function GetDepthBuffer ( buffer:THandle ): THandle;

Returns the specified buffer's depth texture.

[Examples]

BufferWidth

• C: int BufferWidth( TBuffer buffer )
• C++: int Buffer::GetWidth( void ) const
• C#: BufferWidth:Int( buffer:TBuffer )
• Pascal: function BufferWidth ( buffer:THandle ): Integer;

Returns width of the specified buffer.

[Examples]

BufferHeight

• C: int BufferHeight( TBuffer buffer )
• C++: int Buffer::GetHeight( void ) const
• C#: BufferHeight:Int( buffer:TBuffer )
• Pascal: function BufferHeight ( buffer:THandle ): Integer;

Returns height of the specified buffer.

[Examples]

Global Commands

SetBuffer

• C: void SetBuffer( TBuffer buffer )
• C++: void Buffer::Set( void )
• BlitzMax: SetBuffer( buffer:TBuffer )
• Pascal: procedure SetBuffer ( buffer:THandle );

Sets the specified buffer as the active buffer.

[Examples]

SaveBuffer

• C: int SaveBuffer( TBuffer buffer, str filename, int quality=85 )
• C++: int Buffer::SaveBuffer( const_str filename, int quality )
• BlitzMax: SaveBuffer:Int( buffer:TBuffer, cs:Byte Ptr [, quality:Int] )
• Pascal: function SaveBuffer ( buffer:THandle; name:PAnsiChar; quality:Integer=85 ): Integer;

Saves the specified buffer to a file (saving the BackBuffer() is like taking a screenshot). Quality is only used for JPG/JPEG files. Leadwerks Engine 2 supports saving to JPG/JPEG, TGA, and PNG files.

[Examples]

BackBuffer

• C: TBuffer BackBuffer( void )
• C++: Buffer Window::GetBackBuffer( void )
• BlitzMax: BackBuffer:TBuffer()
• Pascal: function BackBuffer: THandle;

Returns the default Leadwerks back buffer.

[Examples]

CurrentBuffer

• C: TBuffer CurrentBuffer( void )
• Pascal: function CurrentBuffer: THandle;

Returns the current buffer.

[Examples]

Capabilities Commands

MaxColorBuffers

• C: int MaxColorBuffers( void )
• C++: static int Buffer::GetMaxColors( void ) const
• BlitzMax: MaxColorBuffers:Int()
• Pascal: function MaxColorBuffers: Integer;

Returns the maximum number of color attachments allowed on the user's hardware.

[Examples]