Headless mode

Headless mode is a software capability of working on a device without access to Graphical User Interface (GUI). The term "headless" is also used when software does not require the presence of peripheral devices (like display, keyboard, mouse) or access to them. The absence of peripherals does not cause the failure of initialization or execution processes. However, in this case the software may receive inputs and provide output via other communication interfaces, for example via network or a serial port.

Headless Rendering

Headless configuration allows running LightningChart in a headless/server environment. Expected scenarios include background rendering in software applications without User Interface (UI) and generation of a bitmap image from the chart content. The image then can be passed to the headful system for further rendering.

Basic usage:

var chart = new LightningChart(new RenderingSettings()
{    
    HeadlessMode = true 
});

Headless mode can be activated by setting HeadlessMode flag to true. The property can be accessed via render-options: chart. ChartRenderOptions (for WPF) or chart. RenderOptions (for WinForms). LightningChart automatically detects its usage in the Windows Service type application, thus there is no need to specify the mode.

Additional initialization options

The initialized instance of LightningChart with a missing UI and visual parent will not receive any rendering requests, like sizing the layout or when to render a frame. Furthermore, WPF chart uses these signals to initialize a rendering engine when WinForms does engine initialization during the creation time. Thus, the following operations and configurations must be applied to the chart by the user:

• Define size using chart.Width and chart.Height properties.
• Request rendering engine initialization by calling chart.InitializeRenderingDevice(true) (only for WPF).
• Subscribe to chart.AfterRendering event for implementing the logic of exporting the images.

The chart still reacts to property changes. The rendering of a new frame can be queried by consecutive BeginUpdate() and EndUpdate() call, if it is needed.

Below is the example of code excerpt for headless mode:

    private LightningChart _chart = null;

    private void CreateChart()
    {
        _chart = new LightningChart(new RenderingSettings() { HeadlessMode = true });

        _chart.BeginUpdate();

        _chart.InitializeRenderingDevice();

        _chart.Width = 600;
        _chart.Height = 500;

        _chart.ViewXY.XAxes[0].ValueType = AxisValueType.Number;
        _chart.ViewXY.XAxes[0].SetRange(0, 10);

        PointLineSeries lineSeries = new PointLineSeries(_chart.ViewXY, _chart.ViewXY.XAxes[0], _chart.ViewXY.YAxes[0]);
        _chart.ViewXY.PointLineSeries.Add(lineSeries);

        _chart.AfterRendering += _chart_AfterRendering;

        _chart.EndUpdate();
    }

    int count = 0;
    private void _chart_AfterRendering(object sender, AfterRenderingEventArgs e)
    {
        _chart.CopyToClipboard();
        // OR
        bool bSaved = _chart.SaveToFile(Directory.GetCurrentDirectory() + "\\" + (count++).ToString() +".png");
    }

Capturing images

The rendered frame can be exported (see Export and printing) in various ways:

• OutputStream property
• SaveToStream method
• CopyToClipboard method
• CaptureToByArray method
• SaveToFile method

In general, bitmap stream is preferred. Also, ViewXY chart supports EMF, SVG in headless mode in SaveToStream and SaveToFile methods.

Diagram of example usages.

Limitations and Requirements

Threads

Headless configuration allows using LightningChart for a background work without placing it inside a visual parent and without access to the chart from the foreground thread (GUI thread). During the creation of the LightningChart instance, the properties of a chart must be updated within the same thread that has created the chart.

• The COM threading model, called “apartment”, must be STA (Single Thread Apartment), not MTA (Multi Thread Apartment). For an ordinary UI application, STA is the default model, whereas MTA state is default for Windows Services.
• All access, i.e. update, creation and disposing, must be made via chart's thread. UI must be touched only from GUI thread. Thus, if there are interaction operations required, they should be moved from chart’s thread to GUI thread. Note! LightningChart can be run on GUI thread.
• The thread must have a valid and active message queue pump. For example, run Application.Run on the thread.

Chart Update

LightningChart uses a single buffer on rendering, thus exporting of a new image will be handled after the exporting of the previous image is finished. The synchronous configuration (ChartUpdateType.Sync) provides a rendering of an image straight after receiving a request to update the properties of a chart. Sync mode should be enabled for the headless mode to enable faster and uninterrupted performance.

Engine support

Both DirectX 9 & 11 engines work in headless mode. However, only DirectX 11 can be used in Windows Services type applications due to the limitations of MS DirectX.

Licensing

By default, Windows Service executes in the security context of a system user account. Installation of a trial and development license is impossible. For this reason, the service application must contain a valid Deployment Key or be running with credentials of a normal user with an active license (trial / development).

Example solution

LightningChart SDK comes with an example Visual Studio solution (DemoService.sln) containing:

• Service
• Console application
• Client application for WPF

DemoService.sln can be found in C:\ProgramData\LightningChart\LightningChart .NET SDK v.12\DemoService folder.

When starting up the WPF client, it shows a frame container in the middle of the window.

WPF client app. After Start, Connect and Generate Data, it shows continuously updating image stream.

Headless demo service – client internal operation of messages with named pipes and background thread illustrated.