The Basics

Property arrays are properties and/or data items like PeData.Y, PeString.SubsetLabels, PeColor.PointColors, and many others that have multiple values defined by one or two indices. These property arrays are dynamic in that they grow as you increase the indices used to set items. Some property arrays have default elements defined and others are empty by default.

Some examples of property arrays with default elements are PePlot.SubsetLineTypes, PePlot.SubsetPointTypes, and PeColor.SubsetColors.

Some examples of property arrays empty by default are PeData.SubsetsToShow, PeLegend.SubsetsToLegend, and PeGrid.MultiAxesSubsets.

It is important to realize that a property array has a size and this size is often used to control image construction. If you are continuously manipulating property arrays. If they grow dynamically, you also need a way to shrink or empty the property array. This can be accomplished using the Clear method. For example, RandomSubsetsToGraph is a common property array that needs to be emptied or resized. The following code shows how to empty this property array.

Also note that PeFunction.Reset() will empty the control of all property settings and revert the object to its default state. This is easier and the recommended approach when you need to reset the state of the object due to repeatedly changing the object.

Regarding Jagged Data or PeData.JaggedData set to True.  We recommend only setting JaggedData = True if necessary. Note that Direct3D does not currently support ComputeShader use for JaggedData.

Use PeData.GetJaggedPointsX and similar functions to get the size (number of data Points) of jagged array.

Use PeData.SetJaggedPointsX and similar functions to set the size of jagged array.

It is not necessary to set the size of an array as the array will grow automatically, but setting the size may help with memory reallocations if spoon-setting large amounts of data.

Complete Methods Reference

The following tables list all methods available on the data property array indexer classes. Method signatures shown uses float as the element type; substitute double for the "ii" variants or Color/peColor32 for PointColors as shown in the type mapping above.

Size and Information

Initialize and Clear

Block Copy In – Non-Jagged Data

These methods copy data from your application arrays into the chart. FastCopyFrom methods call ProEssentials.Api.PEvset / PEvsetW which block copies the source bytes directly into the chart using memcpy – the fastest approach. CopyFrom performs a managed element-by-element copy.  Many of our .Net examples use FastCopyFrom so search our demo projects to find specific use examples.

Copy In – Jagged Data

These methods are used when JaggedData = True. Each method operates on a single subset, allowing subsets to have different numbers of points.

Copy Out

Real-Time Append

These methods support real-time data updating. Existing data shifts to make room for new data unless CircularBuffers is True, in which case a circular buffer eliminates the shifting overhead. After calling AppendData on a Graph Object (Pego), the chart auto-regenerates. For other objects, call ReinitializeResetImage after appending.

Zero-Copy Pointer Reference

Instead of copying data to the chart, these methods tell ProEssentials where your data already exists in memory. The chart reads directly from your arrays – no copy overhead. This is the most efficient approach for large datasets and for sharing the same data across multiple chart objects. Arrays must remain in scope and be pinned for the lifetime of the chart. The GigaPrime3D demo demonstrates data reuse between 3 charts using this approach. Call PeFunction.Reset() or the no-argument overload to clear the pointer reference.

Data Binding

Choosing a Data Passing Strategy

ProEssentials is a native C/C++ component that renders directly via Direct2D, Direct3D, and GDI+ to a Windows device context. This low-level architecture means data handling follows classic C/C++ and C# basic array patterns: simple contiguous blocks of memory. Gigasoft strongly recommends that you maintain your data in standard arrays within your application before passing (or passing by reference) to ProEssentials.

.NET Wrapper Transparency

The .NET interfaces (Gigasoft.ProEssentials.dll) are thin wrappers around the native PEGRP64H.DLL (64-bit) or PEGRP32H.DLL (32-bit). Understanding this helps you optimize. When using the C++ DLL API directly, the same data-handling capabilities are accessed through the corresponding DLL functions:

Quick Reference Guidelines

1. For Non-Jagged mode, set Subsets and Points before passing data.

2. For <100K points, simple indexers (PeData.Y[s,p] = val) are fine.

3. For 100K–500K points, use FastCopyFrom() – simple and fast.

4. For >500K points or shared data, consider UseDataAtLocation() for zero-copy efficiency.

5. Keep your data in application arrays – maintain clear separation from the chart.

6. Use JaggedData only when subsets genuinely have different point counts.

7. Call ReinitializeResetImage() after setting or changing data (Graph Objects auto-regenerate after AppendData).

Related Demo Examples

Explore these examples in the PeDemo application (default install: C:\ProEssentials10\Demo) for working implementations:

Note on PointColors

PeColor.PointColors uses the same method patterns as the data properties above, but accepts Color or peColor32 types instead of float/double. When using FastCopyFrom with int[] arrays for PointColors, note that int colors should be formatted as BGR instead of RGB when passing to the native DLL in bulk. The static helper method ColorArrayToPeColor32() on TwoDimensionalColorArray can convert System.Drawing.Color arrays to peColor32 arrays for use with FastCopyFrom methods.

Deep Dive Property Array Indexer Classes

The technology behind property arrays is known as Indexers. These are special .NET classes to facilitate working with dynamic lists using common array nomenclature.

ProEssentials defines several Indexer classes to work with different types of property arrays. You will never allocate these classes yourself, but inherently use them as embedded features. You may see mention of these classes when working with ProEssentials. Just note they are internal mechanisms to facilitate working with arrays.

The base classes provide core array operations (Clear, Initialize, Copy, GetLength, etc.) used by all property arrays:

The primary data property arrays (X, Y, Z, W) use an extended class that inherits everything from TwoDimensionalFloatArray and adds real-time append and additional block-copy overloads:

TwoDimensionalFloatArrayEx adds AppendData (append new points per subset for real-time) and AppendSubset (append new subset items per point for real-time) to the base class methods. TwoDimensionalDoubleArray and TwoDimensionalColorArray include these methods directly.

Data Property Type Mapping

All data property arrays share the same set of methods. The only difference is the element type used in method signatures. When reading the methods table below, substitute the appropriate type for your property:

Use the double-precision "ii" variants (Yii, Xii, etc.) when you need greater precision. Set the corresponding UsingYDataII property to True and pass data through PeData.Yii instead of PeData.Y.