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

FreeBSD Manual Pages

  
 
  

home | help
GLDB-GUI(1)		       Bugle user manual		   GLDB-GUI(1)

NAME
       gldb-gui	- graphical OpenGL debugger

SYNOPSIS
       gldb-gui	your-program [argument...]

GETTING	STARTED
       The command above will start gldb-gui, but will not start your program.
       To do that, use Run a Run. Your program will automatically stop if it
       generates an OpenGL error. You can also stop it manually	by selecting
       Run a Stop (Ctrl+Break).	See the	section	called "SETTING	BREAKPOINTS"
       for information on stopping your	program	when it	calls particular
       OpenGL functions. You can continue your program with Run	a Continue
       (Ctrl+F9), continue until the next OpenGL function call with Run	a Step
       (F8), or	kill it	with Run a Kill	(Ctrl+F2).

	   Tip
	   Your	program	can only be stopped or killed when it calls an OpenGL
	   function. If	your program updates its display only when necessary,
	   it may not stop immediately.	You can	often force it an update by
	   placing another window over your program and	then removing it
	   again.

       The interface is	separated into a number	of tabs. You can browse	them
       at any time, but	the information	will only be up-to-date	when your
       program is stopped. When	your program is	running, the status bar	will
       contain the text	Running.

EXAMINING OPENGL STATE
       The initial tab is the State tab. It shows all OpenGL state that	is
       textual rather than an image. The state is organised roughly more or
       less according to the state tables in the OpenGL	specification.[1]
       OpenGL has an overwhelming amount of state, so some tools are provided
       to make it easier to find answers:

       o   To find a specific state, press Ctrl+F. This	opens a	text entry box
	   where you can type in the name of the state.

       o   To show only	the states that	changed	since the last time the
	   program was stopped,	check the Show only modified checkbox. These
	   states are also shown in bold.

       o   To track only a small set of	states,	check the checkboxes next to
	   those states, then check the	Show only selected checkbox.

       o   To save all the states to an	XML file, click	the Save button.

   Examining buffers
       The Buffers tab shows OpenGL buffers (vertex buffer objects). The
       Buffer combobox allows a	buffer to be selected. By default, the buffer
       is decoded as a sequence	of unsigned bytes, but a format	specification
       can be filled in	below the combobox to control the decoding. It works
       best when the entire buffer contains repetitions	of repetitions of a
       single structure	format.

       Suppose that the	buffer contains	a sequence of vertices,	each
       consisting of a 3 GLfloats for the position, 3 unsigned bytes for a
       colour, and a byte of padding to	make the stride	16 bytes. Then fill in
       the format field	with fffbbb_ or	more compactly,	3f3b_. A description
       of the available	letters	for specifying types appears below the entry
       box.

   Examining textures
       The Textures tab	shows OpenGL textures. The Texture combobox allows a
       texture to be selected, with the	currently bound	texture	of each	type
       shown in	bold. For cubemap textures, the	Face combobox allows one of
       the sides to be examined	in detail; the default is to show two views of
       the cube	itself.	For 3D textures, a slice may be	selected with the Z
       combobox.

       The apparent size of the	texture	is controlled through the Zoom
       combobox.  Fit makes the	texture	as large as possible while still
       fitting the window. The other settings set a ratio between texels and
       screen pixels. The toolbar also has buttons to
       [IMAGE]<objectinfo>GTK+</objectinfo>[2] [] zoom in,
       [IMAGE]<objectinfo>GTK+</objectinfo>[3] [] zoom out, set	a
       [IMAGE]<objectinfo>GTK+</objectinfo>[4] [] 1:1 ratio, or
       [IMAGE]<objectinfo>GTK+</objectinfo>[5] [] fit to the window size.

       The appearance of the texture may be controlled with the	Mag filter and
       Min filter comboboxes. These settings correspond	to the
       GL_TEXTURE_MAG_FILTER and GL_TEXTURE_MIN_FILTER in OpenGL. However,
       these settings are only used for	displaying the texture,	and do not
       affect your program. The	Level combobox makes it	possible to examine
       specific	texture	levels.	The default (Auto) uses	mipmapping as defined
       by Min filter.

       In some cases, there may	not be enough contrast in the texture to see
       any details (this is particularly true of textures that encode
       non-graphical information, such as lookup tables). Checking Remap range
       will scale the colour range up (or down)	to cover the whole [0, 1]
       range. To perform more detailed image analysis, use the
       [IMAGE]<objectinfo>GTK+</objectinfo>[6] [Copy] button to	copy the
       texture to the clipboard, and paste it into an external application
       such as the GIMP.

	   Note
	   The copy feature is only available when compiled with GTK+ 2.6 or
	   later.

   Examining framebuffers
       Framebuffers may	be viewed in much the same way as textures (see	the
       section called "Examining textures"). The Framebuffer may be set	to
       either the current window-system	framebuffer, or	to a framebuffer
       created with glCreateFramebufferEXT. Pbuffers that are no the current
       drawable	are not	supported.

       Within a	framebuffer, Buffer may	be set to the front buffer, back
       buffer, depth buffer, stencil buffer or an auxiliary buffer, depending
       on which	buffers	actually exist.

   Examining shaders
       The Shaders tab shows the source	of low-level ARB shaders and
       high-level GLSL shaders.	Vendor-specific	shader extensions are not
       supported. The current shader of	each type is shown in bold in the
       combobox.

       Further information about the shader may	be found on the	State tab.

SETTING	BREAKPOINTS
       The Breakpoints allows breakpoints to be	set on specific	OpenGL
       functions. Immediately before calling the function, your	program	will
       be stopped and the status bar will indicate which function caused the
       breakpoint.

       Click Add to set	a new breakpoint, and enter the	name of	the function
       into the	dialog box that	appears. To remove a function from the list,
       click Remove. If	you are	likely to want to break	on that	function
       later, it is easier to deselect the Enabled checkbox for	the function,
       and select it again later.

	   Tip
	   Keep	in mind	that a function	may have multiple aliases (for
	   example, glBeginQuery and glBeginQueryARB), and you need to select
	   the right one.

       By default, gldb-gui will stop when a function generates	an OpenGL
       error. This can be disabled by deselecting Break	on errors. Note	that
       function	breakpoints occur before the function is called, but errors
       occur afterwards, so gldb-gui may stop twice for	the same function.

INTERACTING WITH GDB
       When your program is stopped, the Backtrace tab shows the current call
       stack of	your program, as gdb would. The	first few frames (usually
       those up	to run_filters)	will be	internal to bugle.

       To further examine the state of your program, select Run	a Attach GDB.
       Provided	that you have xterm and	gdb installed, this will open a
       terminal	window running gdb, already attached to	your program. Once you
       have finished, you may either quit gdb and detach it from your program,
       or keep it open and continue in gdb.

	   Note
	   Your	program	needs to be running from the point of view of gdb for
	   gldb-gui to function	correctly.

REMOTE DEBUGGING
       Debugging on a single machine is	not always practical, because the
       target application may run full-screen, or take over the	keyboard or
       mouse.

       Several options exist to	use gldb-gui on	a separate machine to the
       target application. However, all	of them	require	trust between the two
       machines	involved as the	debugging protocol is not error-checked	and so
       it would	be easy	for either a rogue target to attack gldb-gui or	vice
       versa.

       Regardless of the method	used, the GL implementation running the
       debugger	must in	some respects be at least as capable as	the display
       running the target application. Specifically, any texture that you view
       is loaded into an equivalent texture in the debugger, and so the
       texture target and dimensions must be supported there. Note that	even
       if bugle	was built for OpenGL ES, the debugger will use OpenGL.

   Remote X11, target on local display
       The easiest and most robust option is to	rely on	the networking in the
       X Windowing System. From	the machine containing the target, start
       gldb-gui	with a suitable	DISPLAY	to place the GUI on a remote machine.
       Then go to Options a Target and set the display to the local machine
       (usually	:0.0).

       Although	X11 can	directly connect to a remote display over the network,
       this is not an encrypted	connection and may not be secure. SSH has an
       X-forwarding option (-x), but with the default setting it does not
       forward GLX and so it will not work if you have compiled	gldb-gui with
       OpenGL support. However,	the -Y forwards	the connection as trusted, and
       in this mode GLX	is supported. Please see security(7) to	understand the
       security	implications of	this before you	proceed.

   Remote X11, target on remote	display
       The same	setup as above may be used in reverse: the target runs on a
       remote display, while gldb-gui runs on the local	display. The
       disadvantage of this is that the	application is now using indirect
       rendering, which	may affect its performance as well as its behaviour.

   SSH-tunnelled debugger protocol
       This scenario is	experimental and fragile. The debugger and target
       execute on separate machines, and communicate over SSH rather than
       through a local pipe. Because the debugger protocol was not designed
       for networking, this currently places severe restrictions on the
       machines	used:

       o   They	must use the same byte representations for types. In
	   particular, they must have the same endianness, and it may be
	   necessary for them to have the same word size.

       o   Any types used on the target	must also be known to the debugger.
	   Ideally, one	should use the same version of bugle, compiled with
	   the same compiler and the same OpenGL headers. In some cases	it may
	   be sufficient to copy src/data/gl.tu	from one build to another and
	   re-build (but do not	run make clean,	as this	will cause the copied
	   file	to be regenerated).

       o   The Backtrace tab and the Attach GDB	action will not	work.

       To use this mode, go to Options a Target	and change the mode to Remote
       via SSH.	In the remote host, put	the hostname as	it will	be passed to
       ssh(1) (it can also contain a username).	You must also configure	ssh to
       log into	the machine without prompting for a password.

   TCP/IP connection
       This is similar to the SSH option, but does not require SSH to be
       available, making it suitable for embedded systems with OpenGL ES.
       First, start the	application on the target, with	the following
       environment variables:

       o   LD_PRELOAD=libbugle.so

       o   BUGLE_DEBUGGER=tcp

       o   BUGLE_DEBUGGER_PORT=port

       o   BUGLE_DEBUGGER_HOST=host (optional)

       This will open a	listener on port. By default, it will listen on	all
       interfaces, but can be made to bind to a	specific interface by setting
       BUGLE_DEBUGGER_HOST.

       Once the	target has been	started, go to Options a Target	and change the
       mode to Remote via TCP/IP. You will then	be able	to fill	in the host
       and port	of the target. Once this setup is done,	select Run a Run to
       start the debugging session.

	   Warning
	   This	mode does not use any kind of authentication or	encryption, so
	   should only be used on a trusted network.

AUTHOR
       bugle is	written	and maintained by Bruce	Merry.

SEE ALSO
       bugle(3), ssh(1), security(7)

NOTES
	1. OpenGL specification.
	   http://www.opengl.org/registry/doc/glspec21.20061201.pdf

	2. [set	$man.base.url.for.relative.links]/gtk-zoom-in.png

	3. [set	$man.base.url.for.relative.links]/gtk-zoom-out.png

	4. [set	$man.base.url.for.relative.links]/gtk-zoom-100.png

	5. [set	$man.base.url.for.relative.links]/gtk-zoom-fit.png

	6. [set	$man.base.url.for.relative.links]/gtk-copy.png

BUGLE 0.0.20091026		  March	2009			   GLDB-GUI(1)

NAME | SYNOPSIS | GETTING STARTED | EXAMINING OPENGL STATE | SETTING BREAKPOINTS | INTERACTING WITH GDB | REMOTE DEBUGGING | AUTHOR | SEE ALSO | NOTES

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

home | help