Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
al_set_target_bitmap(3)				       al_set_target_bitmap(3)

       al_set_target_bitmap - Allegro 5	API

	      #include <allegro5/allegro.h>

	      void al_set_target_bitmap(ALLEGRO_BITMAP *bitmap)

       This function selects the bitmap	to which all subsequent	drawing	opera-
       tions in	the calling thread will	draw to.  To return to	drawing	 to  a
       display,	 set the backbuffer of the display as the target bitmap, using
       al_get_backbuffer(3).  As a convenience,	you may	also  use  al_set_tar-

       Each  allegro  bitmap  maintains	two transformation matrices associated
       with it for drawing onto	the bitmap.  There is a	view matrix and	a pro-
       jection matrix.	When you call al_set_target_bitmap, these will be made
       current for the bitmap, affecting global	OpenGL and DirectX states  de-
       pending on the driver in	use.

       Each  video bitmap is tied to a display.	 When a	video bitmap is	set to
       as the target bitmap, the display that the bitmap belongs to  is	 auto-
       matically  made	"current" for the calling thread (if it	is not current
       already).  Then drawing other bitmaps which are tied to the  same  dis-
       play can	be hardware accelerated.

       A single	display	cannot be current for multiple threads simultaneously.
       If you need to release a	display, so it is not current for the  calling
       thread, call al_set_target_bitmap(NULL);

       Setting a memory	bitmap as the target bitmap will not change which dis-
       play is current for the calling thread.

       On some platforms, Allegro automatically	backs up the contents of video
       bitmaps	because	 they  may  be	occasionally  lost  (see discussion in
       al_create_bitmap(3)'s documentation).  If you're	completely  recreating
       the  bitmap  contents  often (e.g.  every frame)	then you will get much
       better performance by creating the target bitmap	 with  ALLEGRO_NO_PRE-
       SERVE_TEXTURE flag.

       OpenGL note:

       Framebuffer  objects  (FBOs) allow OpenGL to directly draw to a bitmap,
       which is	very fast.  When using an OpenGL display, if all of  the  fol-
       lowing  conditions are met an FBO will be created for use with the bit-

       o The GL_EXT_framebuffer_object OpenGL extension	is available.

       o The bitmap is not a memory bitmap.

       o The bitmap is not currently locked.

       In Allegro 5.0.0, you had to be careful as an FBO would be kept	around
       until   the  bitmap  is	destroyed  or  you  explicitly	called	al_re-
       move_opengl_fbo(3) on the bitmap, wasting  resources.   In  newer  ver-
       sions,  FBOs  will  be freed automatically when the bitmap is no	longer
       the target bitmap, unless you have called al_get_opengl_fbo(3)  to  re-
       trieve the FBO id.

       In the following	example, no FBO	will be	created:

	      lock = al_lock_bitmap(bitmap);
	      al_put_pixel(x, y, color);

       The  above allows using al_put_pixel(3) on a locked bitmap without cre-
       ating an	FBO.

       In this example an FBO is created however:

	      al_draw_line(x1, y1, x2, y2, color, 0);

       An OpenGL command will be used to directly draw the line	into the  bit-
       map's associated	texture.

       al_get_target_bitmap(3),	al_set_target_backbuffer(3)

Allegro	reference manual			       al_set_target_bitmap(3)


Want to link to this manual page? Use this URL:

home | help