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.
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.
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);
}#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.
[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);
}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.
MyApp.exe dev1 C:\Temp\onscryn-dev16. 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.