onscryn

How your app is launched and how it starts the SDK

7 min read

An SDK app is started by the Onscryn agent, not by a person. Knowing exactly how it is started, and in what order your app should bring the SDK up and shut it down, removes most integration surprises.

The command line

When someone launches your app, the agent starts it in a Windows session of its own with a fixed set of arguments, followed by anything you entered in the app's Arguments field in the dashboard. The first argument after the executable is the instance id that ties your process to that one session.

The command line an SDK app is started with
PositionValueWhat it is for
1Instance idIdentifies this one session. Pass it to Onscryn_Start as instanceId
2Output folderA working folder for this session. Pass it as outputDir. Frame files go here when you test with file dump
3pipeTells your app to stream to Onscryn. Your own builds can accept anything else for local testing
4Image qualityFrom the app's setting in the dashboard, 1 to 100. Pass it as tileQuality
5Tile formatFrom the app's setting: webp, jpeg or raw. Map it to tileFormat 0, 1 or 2
6 and onYour argumentsWhatever you typed in the app's Arguments field, passed through unchanged
The executable path itself comes first, as usual. Positions here count from the first argument after it.

Start the SDK

Call Onscryn_Start once, after your main window exists. Pass the instance id from the command line, the transport, and the quality settings. Leave relayPipe empty to use the default pipe for the instance.

A zero-initialized options struct is a good start. Auto input and the auto UI tree are on unless you set their disable flags, so an app that does nothing else already gets working input and a UI tree.

The options passed to Onscryn_Start
FieldWhat it doesDefault
instanceIdThe session's instance id, from the command lineRequired
transport0 writes frames to files for local testing, 1 streams to Onscryn0
outputDirWhere file-dump frames and logs goNone
relayPipeA custom pipe name. Leave null to use the default for the instancenull
appInvisible1 means never show a window on any desktop0
tileQualityImage quality from 1 to 10080 when unset by the app's setting
tileFormat0 for WebP, 1 for JPEG, 2 for raw BGRA0
disableAutoInjectInput1 turns off automatic delivery of browser input, so you handle it0 (automatic input is on)
disableAutoUiTree1 turns off the automatic UI tree, so you send your own0 (automatic UI tree is on)
Zero-initialize the struct. The two disable fields are inverted on purpose, so an untouched struct gives the behavior that works out of the box.

Set callbacks

Call Onscryn_SetCallbacks with the events you care about. Any callback may be left null. They arrive on SDK threads, not on your UI thread, so hand work to the UI thread yourself if you touch controls. The callbacks are listed in the API reference.

In .NET, keep every delegate you pass in a field for the life of the process. A delegate that is only referenced locally can be garbage collected, and the next callback then crashes the app.

Register actions and printing

If you expose named actions, register them right after the callbacks. If you want browser printing, call Onscryn_EnablePrinting once. Both are optional, and both are covered in their own pages.

Shut down cleanly

The close callback tells your app that Onscryn wants it to close, for example when the session is ending. Close your main window in response. In your own shutdown path call Onscryn_Stop once, before the process exits.

If your app exits before it has presented a first frame, the session is marked failed with a message that the app exited before producing a first frame. That is the signal to check the DLL, the bitness and Onscryn_Start's return value.

Set DPI awareness first

Make your process per-monitor DPI aware before you create any window. The picture the browser scales then matches the pixels your app drew, and text stays sharp. In .NET call SetProcessDpiAwarenessContext with the per-monitor v2 context at the top of Main.

Want it set up
with you?