Re: [AD] Conserving OpenGL FBOs

[Peter Wang <novalazy@xxxxxxxxxx>]

On 2011-03-02, Trent Gamblin <trent@xxxxxxxxxx> wrote:
> On Wed, 2011-03-02 at 14:39 -0600, Trent Gamblin wrote:
> > I've got a patch that is supposed to use fbos from a pool (of 8 right
> > now). I don't get any slowdown in ex_bitmap_target, and my game, which
> > was getting an X error about out of resources, is working now... so I
> > think this patch is at least partially right. I'd like to have someone
> > review it if possible before I commit it though. It's attached. Would
> > appreciate any comments.
> 
> Elias already kindly had a look at the patch, and suggested that the old
> fbo could be deleted before the new one is created. The new patch does
> this but is otherwise the same. So now no more than
> ALLEGRO_MAX_OPENGL_FBOS will be used (with the first patch it was
> ALLEGRO_MAX_OPENGL_FBOS+1).

Thanks for doing this.

The documentation needs updating.  Below is what I have so far.
I'm not sure what we can say about the lifetime of the FBO returned by
al_get_opengl_fbo (see the XXX).  I don't think we should lock ourselves
into the current implementation.

I am considering backporting the change to the 5.0 branch but since this
changes the documented behaviour of al_get_opengl_fbo I will hold off,
unless there are other opinions.

Peter

diff --git a/docs/src/refman/graphics.txt b/docs/src/refman/graphics.txt
index 2169175..de46e5a 100644
--- a/docs/src/refman/graphics.txt
+++ b/docs/src/refman/graphics.txt
@@ -748,19 +748,15 @@ OpenGL note:
 
 Framebuffer objects (FBOs) allow OpenGL to directly draw to a bitmap, which is
 very fast. However, each created FBO needs additional resources, therefore an
-FBO is not automatically assigned to each non-memory bitmap when it is created
-(as is done with textures).
+FBO is not automatically assigned to each bitmap when it is created.
 
 When using an OpenGL display, only if all of the following conditions are met an
-FBO will be created for the bitmap:
+FBO will be created (or recycled) for use with the bitmap:
 
 * The GL_EXT_framebuffer_object OpenGL extension is available.
 * The bitmap is not a memory bitmap.
 * The bitmap is not currently locked.
 
-Once created, the FBO is kept around until the bitmap is destroyed or you
-explicitely call [al_remove_opengl_fbo] on the bitmap.
-
 In the following example, no FBO will be created:
 
     lock = al_lock_bitmap(bitmap);
@@ -771,14 +767,20 @@ In the following example, no FBO will be created:
 The above allows using [al_put_pixel] on a locked bitmap without creating an
 FBO.
 
-In this example an FBO is created however:
+In this example an FBO is created, or recycled:
 
     al_set_target_bitmap(bitmap);
     al_draw_line(x1, y1, x2, y2, color, 0);
 
-And an OpenGL command will be used to directly draw the line into the bitmap's
+An OpenGL command will be used to directly draw the line into the bitmap's
 associated texture.
 
+> *Note:* Before Allegro 5.1.0, the FBO would be kept around until the bitmap
+is destroyed or you explicitly call [al_remove_opengl_fbo] on the bitmap.
+However, FBOs are now automatically freed or recycled once the bitmap is no
+longer the target bitmap.  This may impact on programs that use
+[al_get_opengl_fbo].
+
 See also: [al_get_target_bitmap], [al_set_target_backbuffer]
 
 ### API: al_set_target_backbuffer
diff --git a/docs/src/refman/opengl.txt b/docs/src/refman/opengl.txt
index 5007210..073678a 100644
--- a/docs/src/refman/opengl.txt
+++ b/docs/src/refman/opengl.txt
@@ -93,11 +93,22 @@ Returns the OpenGL FBO id internally used by the given bitmap if it uses one,
 else 0. An FBO is created for a bitmap when you call [al_set_target_bitmap]
 for it.
 
+Warning: since Allegro 5.1.0, the FBO created for a given bitmap may be
+automatically freed or recycled once the bitmap is no longer the target bitmap.
+Hence the id returned is only valid {XXX for how long?}.
+
+See also: [al_remove_opengl_fbo], [al_set_target_bitmap]
+
 ## API: al_remove_opengl_fbo
 
 If the bitmap has an OpenGL FBO created for it (see [al_set_target_bitmap]),
 it is freed. It also is freed automatically when the bitmap is destroyed.
 
+Warning: since Allegro 5.1.0, the FBO created for a given bitmap may be
+automatically freed or recycled once the bitmap is no longer the target bitmap.
+
+See also: [al_get_opengl_fbo], [al_set_target_bitmap]
+
 ## API: al_have_opengl_extension
 
 This function is a helper to determine whether an OpenGL extension is