Linux Certif

Toute la documentation sur la certification Linux LPI

gldb-gui

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 → Run. Your program will automatically stop if it generates an OpenGL error. You can also stop it manually by selecting Run → 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 → Continue (Ctrl+F9), continue until the next OpenGL function call with Run → Step (F8), or kill it with Run → 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 m[blue]OpenGL specification.m[][1] OpenGL has an overwhelming amount of state, so some tools are provided to make it easier to find answers:

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

• 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.

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

• 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 → 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 → 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:

• 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.

• 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).

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

To use this mode, go to Options → 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:

• LD_PRELOAD=libbugle.so

• BUGLE_DEBUGGER=tcp

• BUGLE_DEBUGGER_PORT=port

• 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 → 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 → 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