Documentation
Graphics

ArrayFire provides several visualization primitives allowing you to explore data at run time using state of the art plotting in OpenGL with minimal impact upon compute time.

# Introduction

General purpose computing aside, the GPU is first and foremost a graphics processing machine. Reflecting this reality, ArrayFire ships with a graphics package both with free and commercial versions. Unique to ArrayFire, its graphics engine is designed from the ground-up with GPGPU computing in mind: all primitives draw from memory on the card. Therefore, compute and visualization are both handled by the GPU without any memory transfers between the host CPU and the device. The GPU is left to do what it does best: parallel processing and graphics output while the CPU is left to serial computation and direction of the graphics backend.

Several basic plotting primitives are included with the graphics package including support for the following tasks:

• 2D and 3D line plotting
• volume rendering
• overlaying plots for comparison analysis
• image visualization

# Usage

The ArrayFire graphics package is designed as a separate thread that runs along side any GPU compute threads in your application. The programmer is expected to make graphics calls in the GPU compute threads which are then queued up and executed by the graphics thread in first in first out order. As such, most graphics calls are non-blocking and, furthermore, have lower priority than all other GPU compute calls to the rest of ArrayFire. The graphics system's goal is to draw to the screen in the GPU's spare time, leaving the majority of the GPU's time for compute. Thus, some non-blocking commands will be dropped if necessary unless the blocking fig("draw") command is utilized to force rendering.

The ArrayFire graphics API is divided into two groups: control commands and primitive commands. Various control commands available through fig():

• fig("color", table) ~ alter the color palette (see Color Palettes )
• fig("clear") ~ clear the figure
• fig("draw") ~ redraw the figure (blocking)
• fig("title", name) ~ label the figure with a title
• fig("close") ~ close the figure window (blocking)

Primitive commands instruct the graphics backend to render data to the screen. All primitive commands are non-blocking. Data associated with each primitive command is copied to a drawing queue along with the primitive. Thus, each primitive command will draw the data that was current at the time of its invocation. However, keep in mind the primitive may be dropped unless a fig("draw") command is utilized to force rendering. Primitive commands include: surface(), plot2(), plot3(), image(), volume(), ...

# Examples

The following code generates side-by-side image and line plot of one hundred random samples. Note that fig("draw") is not utilized in this example leaving all graphics commands as non-blocking. Thus, the program generates random samples as quickly as possible and draws the plots as time allows.

#include <arrayfire.h>
using namespace af;
int main(void)
{
while (1) {
array s = randu(10,10);
fig("color","colors");
fig("sub",2,1,1); image(s); fig("title", "image");
fig("sub",2,1,2); plot2(s); fig("title", "plot2");
// fig("draw"); // uncomment to force screen refresh at 30Hz
}
return 0;
}

The following code excerpt comes from the examples/visualization/blip.cpp example, and shows use of plot2(), image(), and surface().

fig("color","heat");
fig("sub",2,1,1); surface(B);
fig("sub",2,3,2); plot2(B(span, 0));
fig("sub",2,3,4); plot2(B(span, N / 2));
fig("sub",2,3,6); image(B);

The following code excerpt comes from the examples/pde/swe.cpp example, and shows use of plot3() and image().

fig("color","mood");
fig("sub",2,1,1); image(eta);
fig("sub",2,1,2); plot3(eta, up, vp);

The following code excerpt comes from the examples/pde/fdtd.cpp example, and shows use of plot2(), surface() and image().

fig("color","heat");
fig("sub",2,2,2); image(ey);
fig("sub",2,2,4); plot2(ey);
fig("sub",2,1,1); surface(ey);

# Color Palettes

The fig() function fig("color", palette) accepts the following color maps:

• default
• colors
• spectrum
• heat
• mood
• red
• blue

# Notes

• ArrayFire GFX does not function properly with MFC-type projects from Visual Studio 2008.
• The gfx window must be a separate window (no embedding into other windows).