Dynamic Surfaces

As for all plots in ILNumerics, all properties of surfaces can be altered dynamically at runtime. It is recommended (but not strictly necessary) to use one of the Surface.Update???() overloads, in order to update any buffer related data, like positions or colors.  Surface.Update???() will be more efficient than using individual surface properties.

If the size of the surface is to be changed frequently, the Surface.Resize() function comes in handy. In situations with dynamically, frequently changing sizes, it is recommended to ‘pre-allocate’ the surface buffers with the largest size needed and afterwards subsequently using one of the Update???() functions to alter the data.

The following example demonstrates the dynamic capabilities of ILNumerics surfaces. The example is found in the Examples section:

A simple sinc surface is created. In every rendering frame the color indices for the grid points are changed. These indices map an arbitrary value to a color in the current colormap, which is then used for the grid point. In addition, a regular Windows Forms button is used to select the next available colormap from the Colormaps enumeration interactively. The surface maintains full interactivity during the updates. It is recommended to use an OpenGL, WebGL or DirectX (not available yet) panel for it.

Let’s quickly step through the code and pay attention to some interesting general aspects: We created the plot cube, the surface and the color bar in one instruction, utilizing C# 3.0 object initializers.

The remaining part of ilPanel1_Load handles interactivity. An anonymous function is defined for handling the BeginRenderFrame event. That event is called for every frame. What our entire handler does is to compute a blending factor from the current frame time. The time in milliseconds is taken from the event argument Parameter property. The time variable is used next to blend between the two predefined A and B matrices.

The result is supplied to the Surface.UpdateColormapped() function. We change the positions and the color data of the grid. Alternatively, one might change the color data only:

One more aspect is worth to shine some light upon: the BeginRenderFrame handler is called rather frequently – around 60 times a second. We seriously don’t want to mess around with the GC in the handler function! In order to clean up all storages created during the handler we just need to enclose the function with an

block. All three temporaries created during the handler execution are immediately cleaned up and its storage can be reused in the next run.

For the second event handler we simply drag a new Windows.Forms.Button onto the panel in the Visual Studio Designer. We keep the default name: button1. All what its handler does is to get the next Colormaps enumeration value, create a new colormap based on that value and to supply it to the Colormap property of the surface.

If we click on the button in the running form, the current colormap changes to the next colormap in the collection. Note how the color bar also automatically adopts to the changed colormap.