DebugScope Documentation

DebugScope is very easy to integrate into your project. This guide will run you through the simple steps.

If you're running the application on an actual iPhone/iPad/iPod device then a wifi connection is necessary to connect.

Sample Application

A sample application showing a number of the features provided is included. The sample app is an iOS application, and is located in the iOS Test Application folder within this disk image.

This application can be run either within the iOS simulator, or on an actual iPhone device. The host and port displayed in the top left of the screen is what you will need to provide to the DebugScope application in order to connect.

Now you've seen it working, let's get it integrated into your own project.

Set Up

Firstly, include the files provided in the source folder into your application. Once you have done this there are 3 snippets of code that you will need to place in your application.

Put this snippet of initialisation code at a point where your application is being launched

// ********************
// Initialise debug tools
debugNetworkManager = new libpixel::DebugNetworkManager();
// ********************

Put this snippet of deinitialisation code at a point where you're shutting down your application

// ********************
// Shutdown debug tools
delete debugNetworkManager;
delete libpixel::DebugVariableManager::Instance();
// ********************

The network code needs to be processed regularly, insert this snippet somewhere within your main loop

// ********************
// Update debug tools
// ********************


There are two use cases for DebugScope. DebugScope support altering variables, but it also supports triggering callbacks.


Defining variables is very easy. Preprocessor defines are provided to simplify the process. These will automatically optimise out to proper variables and proxy classes when you define PIXELBALLOON_BUILD_RELEASE.

There are a number of debug variable types. In all cases name defines the name of the variable, and location defines a string value that will be used to display it in DebugScope. Value defines the default value of the variable. Dotted paths will be used to form hierarchy in the application.

In the case of integer and float values they also require a min and max value, these specify the minimum and maximum values that will be used for the sliders in the application. Note that this does not limit the actual values of the variable. Numbers entered manually in the text box can be outside this range.

DEFINE_DEBUG_STRING(name, location, value);
DEFINE_DEBUG_BOOL(name, location, value);
DEFINE_DEBUG_INTEGER(name, location, value, min, max);
DEFINE_DEBUG_FLOAT(name, location, value, min, max);
DEFINE_DEBUG_COLOUR(name, location, r, g, b, a);

There is one additional special debug variable type: function. This will place a button in DebugScope, which when pressed will execute the callback in your code. The callback has a void return type, and a void* parameter for user data.

void ExampleCallback(void* userData)

DEFINE_DEBUG_FUNCTION(SayHello, "example.SayHello", &ExampleCallback);

If you want to set user data for the variable, then you set it via the following function. Note that the debug variable does not take ownership of this data, you are responsible for freeing the data (and setting the user data back to 0 in the variable if necessary)


If you wish to reference debug variables listed in another file then you can do so with the EXTERN_* defines.



At present the library is not thread-safe. Do not set the debug variables across threads. This will be changed in a future release.

Only global variables are currently supported, don't declare variables as class members.


If you have any questions or suggestions then please contact me on


The code and application are provided under the permissive zlib License.

Copyright (c) 2011 Pixel Balloon Ltd

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.


If you find this software useful, please consider donating to help further development