Deal with FrameBuffers as render targets and textures. Color and Depth buffers need to be allocated and managed.

So we need to be baked within an oven so we will talk about the return from the bake function rather than the module function.

local framebuffers=oven.rebake("wetgenes.gamecake.framebuffers")

local fbo=framebuffers.create(256,256,0)	-- a 256x256 texture only
local fbo=framebuffers.create(256,256,-1)	-- a 256x256 depth only
local fbo=framebuffers.create(256,256,1)	-- a 256x256 texture and depth
local fbo=framebuffers.create()				-- 0x0 and we will resize later

local fbo=framebuffers.dirty()
local fbo=framebuffers.dirty(x,y)
local fbo=framebuffers.dirty(x,y,framebuffers.NEED_TEXTURE_AND_DEPTH)
local fbo=framebuffers.dirty(0,0,0,{
    depth_format={gl.DEPTH_COMPONENT32F,gl.DEPTH_COMPONENT,gl.FLOAT},
    texture_format={gl.RGBA,gl.RGBA,gl.UNSIGNED_BYTE},
    TEXTURE_MIN_FILTER=gl.LINEAR,
    TEXTURE_MAG_FILTER=gl.LINEAR,
    TEXTURE_WRAP_S=gl.CLAMP_TO_EDGE,
    TEXTURE_WRAP_T=gl.CLAMP_TO_EDGE,
}) -- note this table will be returned as the fbo

Create a new framebuffer object and optionally provide an inital size and depth. The depth can use -1,0,1 or the following verbose flags framebuffers.NEED_DEPTH,framebuffers.NEED_TEXTURE or framebuffers.NEED_TEXTURE_AND_DEPTH to request a depth buffer(1,-1) or not(0).

Finally you can pass in a table to be returned as the fbo that contains defaults or set defaults in the fbo that is returned.

fbo.depth_format={gl.DEPTH_COMPONENT32F,gl.DEPTH_COMPONENT,gl.FLOAT}

Can be used to control exactly how a depth buffer is allocated with gl.TexImage2D when you care about that sort of thing, IE hardware issues.

fbo.texture_format={gl.RGBA,gl.RGBA,gl.UNSIGNED_BYTE}

Can be used to control exactly how a texture buffer is allocated with gl.TexImage2D when you care about that sort of thing, IE hardware issues.

fbo.TEXTURE_MIN_FILTER=gl.LINEAR
fbo.TEXTURE_MAG_FILTER=gl.LINEAR
fbo.TEXTURE_WRAP_S=gl.CLAMP_TO_EDGE
fbo.TEXTURE_WRAP_T=gl.CLAMP_TO_EDGE

These can be used to control default TexParameters in the fbo.

fbo.no_uptwopow=true

By deafult we will use power of 2 sizes for the fbo that fit the requested size. This disables that and doing so will of course cause problems with some hardware. Generally if you avoid mipmaps it probably wont be a problem.

See #lua.wetgenes.gamecake.framebuffers.fbo for all the functions you can call on the fbo returned.

framebuffers.dirty()

Mark all framebuffer objects as dirty by setting fbo.dirty to be true. We do not do anything with this flag but it is used in external code and this is a useful helper function to set the flag.

fbo:bind_depth()

BindTexture the depth texture part of this fbo.

If there is no texture we will bind 0.

fbo:bind_depth_snapshot()

BindTexture the depth snapshot texture part of this fbo.

If there is no snapshot texture we will bind 0.

fbo:bind_depth()

BindFramebuffer the framebuffer of this fbo.

If there is no framebuffer we will bind 0.

fbo:bind_texture()

BindTexture the rgba texture part of this fbo.

If there is no texture we will bind 0.

fbo:bind_texture_snapshot()

BindTexture the rgba snapshot texture part of this fbo.

If there is no snapshot texture we will bind 0.

fbo:check()

Check and allocatie if missing and needed (eg depth texture may not be needed) all our openGL buffers.

fbo:clean()

Free all the opengl buffers.

fbo:download()
fbo:download(w,h,x,y)

Read back color data from a framebuffer and return it in an RGBA PREMULT grd object (which is probably what it is).

If a width,height is given then we will read the given pixels only from the x,y location.

fbo:free_depth()

Free the depth texture only, is safe to call if there is no depth buffer.

fbo:free_frame()

Free the frame buffer only, is safe to call if there is no frame buffer.

fbo:free_snapshot()

Free the snapshot buffers, fbo.texture_snapshot and fbo.depth_snapshot if they exist.

fbo:free_texture()

Free the rgba texture only, is safe to call if there is no rgba buffer.

fbo:mipmap()

Build mipmaps for all existing texture buffers.

fbo:mipmap_depth()

Build mipmaps for our depth buffer if it exists and set TEXTURE_MIN_FILTER to LINEAR_MIPMAP_LINEAR so it will be used.

It is possible this may fail (hardware issues) and the TEXTURE_MIN_FILTER be reset to gl.NEAREST along with a flag to stop us even trying in the future,

fbo:mipmap_texture()

Build mipmaps for our texture buffer if it exists and set TEXTURE_MIN_FILTER to LINEAR_MIPMAP_LINEAR so it will be used.

fbo:pingpong(fbout,shadername,callback)
framebuffers.pingpong({fbin1,fbin2},fbout,shadername,callback)

Render from one or more fbos into another using a fullscreen shader.

Sometime you need to repeatedly copy a texture back and though applying a shader, this is the function for you.

The textures will be bound to tex1,tex2,tex3,etc and the uvs supplied in a_texcoord with a_vertex being set to screen coords so can be used as is.

fbo:render_start()

Start rendering into this fbo.

Push old matrix and set the matrix mode to MODELVIEW

Set fbo.view and reset the gl state.

fbo:render_stop()

Stop rendering into this fbo and restore the last fbo so these calls can be nested.

Restore the old view and old gl state.

Pop old matrix and set the matrix mode to MODELVIEW

fbo:resize(w,h,d)

Change the size of our buffers, which probably means free and then reallocate them.

The w,h,d use the same rules as framebuffer.create

fbo:snapshot()

Take a current snapshot copy of the texture and depth if they exist, store them in fbo.texture_snapshot and fbo.depth_snapshot for later binding.

framebuffers.start()

Called as part of the android life cycle, since we auto reallocate this does not actually have to do anything. But may do a forced resize in the future if that turns out to be more hardware compatible.

framebuffers.stop()

Called as part of the android life cycle, we go through and call fbo.clean on each fbo to free the opengl resources.