onscryn

SDK quick start: your first streamed app

9 min read

This page takes a small Windows app from nothing to a window in a browser tab. You will start the SDK, hand it frames, check the result locally without any server, then register the app and launch it. The examples use C#, with the C++ equivalent where it differs.

1. Put the SDK next to your app

Copy Onscryn.Capture.dll into your app's output folder, so it sits beside the executable. C++ projects also add onscryn_capture.h to the include path and link Onscryn.Capture.lib. The DLL is 64-bit, so build your app for x64.

2. Describe the SDK to your code

In C++ include the header and you are done. In .NET declare the few calls you need with DllImport. The options struct must match the header field for field, in the same order. A struct that is even one field short makes the SDK read past your buffer.

OnscrynNative.csC#
using System;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
struct OnscrynOptions
{
    [MarshalAs(UnmanagedType.LPWStr)] public string InstanceId;
    public int Transport;            // 0 = write frames to files, 1 = stream to Onscryn
    [MarshalAs(UnmanagedType.LPWStr)] public string OutputDir;
    [MarshalAs(UnmanagedType.LPWStr)] public string RelayPipe;   // null = the default pipe for this instance
    public int AppInvisible;         // 1 = never show a window on a desktop
    public int TileQuality;          // 1-100
    public int TileFormat;           // 0 = WebP, 1 = JPEG, 2 = raw BGRA
    public int DisableAutoInjectInput;  // 0 = the SDK delivers browser input for you
    public int DisableAutoUiTree;       // 0 = the SDK publishes the UI tree for you
}

static class Native
{
    const string Dll = "Onscryn.Capture";

    [DllImport(Dll, CallingConvention = CallingConvention.Cdecl)]
    public static extern int Onscryn_Start(ref OnscrynOptions opts);

    [DllImport(Dll, CallingConvention = CallingConvention.Cdecl)]
    public static extern void Onscryn_Stop();

    [DllImport(Dll, CallingConvention = CallingConvention.Cdecl)]
    public static extern IntPtr Onscryn_AcquireSurface(IntPtr hwnd, int width, int height);

    [DllImport(Dll, CallingConvention = CallingConvention.Cdecl)]
    public static extern void Onscryn_Invalidate(IntPtr hwnd, IntPtr dirtyRectOrNull);

    [DllImport(Dll, CallingConvention = CallingConvention.Cdecl)]
    public static extern void Onscryn_Present(IntPtr hwnd);
}

The full list of calls, with every parameter, is in the API reference.

3. Start it when your window loads

The agent starts your app with an instance id and a few settings on the command line, covered in the next page. For this quick start, read the first two arguments the same way. Call Onscryn_Start once, after your main window exists, and stop it when the app closes.

MainForm.csC#
protected override void OnLoad(EventArgs e)
{
    base.OnLoad(e);

    var args = Environment.GetCommandLineArgs();   // [0] is the exe path
    bool stream = args.Length > 3 && args[3] == "pipe";

    var opts = new OnscrynOptions
    {
        InstanceId = args.Length > 1 ? args[1] : "dev1",
        Transport = stream ? 1 : 0,
        OutputDir = args.Length > 2 ? args[2] : @"C:\Temp\onscryn-dev1",
        TileQuality = args.Length > 4 && int.TryParse(args[4], out var q) ? q : 80,
        TileFormat = 0,
    };

    if (Native.Onscryn_Start(ref opts) == 0)
    {
        MessageBox.Show("Onscryn_Start failed");
        Close();
    }
}

protected override void OnFormClosed(FormClosedEventArgs e)
{
    Native.Onscryn_Stop();
    base.OnFormClosed(e);
}
main.cppC++
#include <windows.h>
#include <wchar.h>
#include "onscryn_capture.h"

// Call after CreateWindow. argv[1] = instance id, argv[2] = output dir, argv[3] = "pipe".
bool StartOnscryn(int argc, wchar_t** argv)
{
    OnscrynOptions opts = {};                       // zero = auto input + auto UI tree stay on
    opts.instanceId  = argc > 1 ? argv[1] : L"dev1";
    opts.transport   = (argc > 3 && wcscmp(argv[3], L"pipe") == 0) ? ONSCRYN_TRANSPORT_PIPE
                                                                   : ONSCRYN_TRANSPORT_FILEDUMP;
    opts.outputDir   = argc > 2 ? argv[2] : L"C:\\Temp\\onscryn-dev1";
    opts.tileQuality = 80;
    opts.tileFormat  = 0;                           // WebP
    return Onscryn_Start(&opts) != 0;
}

4. Hand it frames

The SDK gives you a surface to draw on. Ask for it with your window handle and size, draw into it, say what changed, and present. If your app draws itself with GDI, draw straight into the surface. If it uses standard controls, as WinForms and MFC apps do, ask Windows to render the window into the surface with PrintWindow.

Do this when something changes, not on every timer tick. Passing null to Onscryn_Invalidate means the whole surface changed.

Send the window's pictureC#
[DllImport("user32.dll")] static extern bool PrintWindow(IntPtr hwnd, IntPtr hdc, uint flags);

void SendFrame()
{
    IntPtr hwnd = Handle;
    int w = ClientSize.Width, h = ClientSize.Height;

    IntPtr surface = Native.Onscryn_AcquireSurface(hwnd, w, h);   // a memory DC the SDK owns
    if (surface == IntPtr.Zero) return;

    PrintWindow(hwnd, surface, 1);                 // 1 = client area only
    Native.Onscryn_Invalidate(hwnd, IntPtr.Zero);  // null = everything changed
    Native.Onscryn_Present(hwnd);
}
Owner-drawn GDIC++
case WM_PAINT: {
    RECT rc; GetClientRect(hwnd, &rc);
    HDC sdc = Onscryn_AcquireSurface(hwnd, rc.right, rc.bottom);
    if (sdc) {
        PaintScene(sdc, rc);                       // your existing drawing, aimed at the SDK's DC
        Onscryn_Invalidate(hwnd, &rc);             // or just the part that changed
        Onscryn_Present(hwnd);
    }
    break;
}

Call SendFrame from a background loop that only runs it when the UI has changed, as the reference app does. A fuller treatment, including dialogs and menus, is on the Drawing and sending frames page.

5. Check it on your own machine

You do not need a host to see whether frames are coming out. Run your app with the file-dump transport by leaving out the last argument, and the SDK writes each presented frame to a bitmap in the output folder.

  • Open the folder. A new image should appear each time you click or type in your app.
  • If no image appears, Onscryn_Start returned 0, the DLL is missing or the wrong bitness, or Onscryn_Present is never reached.
  • Each image should match what you see on screen, including controls and text.
cmd
MyApp.exe dev1 C:\Temp\onscryn-dev1

6. Register the app and launch it

Copy your app and Onscryn.Capture.dll to the Windows host, to a folder the agent can reach. In the dashboard, open Admin, then Apps, and add the application with the path to your executable. Set the capture mode to SDK.

Open the app catalog and launch it. A session starts on the host, your app receives its instance id and the pipe argument, and the window appears in the browser tab. Click and type to confirm input reaches it.

If the session fails straight away, the most common cause is the app exiting before it presents a first frame. The troubleshooting page lists the other causes.

Want it set up
with you?