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

FreeBSD Manual Pages

  
 
  

home | help
al_set_target_bitmap(3)				       al_set_target_bitmap(3)

NAME
       al_set_target_bitmap - Allegro 5	API

SYNOPSIS
	      #include <allegro5/allegro.h>

	      void al_set_target_bitmap(ALLEGRO_BITMAP *bitmap)

DESCRIPTION
       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-
       get_backbuffer(3).

       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.

       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-
       map:

       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_set_target_bitmap(bitmap);
	      al_put_pixel(x, y, color);
	      al_unlock_bitmap(bitmap);

       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_set_target_bitmap(bitmap);
	      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.

SEE ALSO
       al_get_target_bitmap(3),	al_set_target_backbuffer(3)

Allegro	reference manual			       al_set_target_bitmap(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=al_set_target_bitmap&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help