Crate zng_view

Source
Expand description

View-Process implementation.

This implementation supports headed and headless apps in Windows, Linux and MacOS.

§Usage

First add this to your Cargo.toml:

[dependencies]
zng = "0.13.0"
zng-view = "0.7.0"

Then call zng::env::init before any other code in main to setup a view-process that uses the same app executable:

use zng::prelude::*;

fn main() {
    zng::env::init!();

    APP.defaults().run_window(|ctx| {
        unimplemented!()
    })
}

When the app is executed run_window gets called and internally starts the view-process. The current executable is started this time configured to be a view-process, init detects this and highjacks the process never returning.

§Software Backend

The webrender/swgl software renderer can be used as fallback when no native OpenGL 3.2 driver is available, to build it the feature "software" must be enabled (it is by default) and on Windows MSVC the clang-cl dependency must be installed and associated with the CC and CXX environment variables, if requirements are not met a warning is emitted and the build fails.

To install dependencies on Windows:

setx PATH %PATH%;C:\Program Files\LLVM\bin
  • Associate CC and CXX with clang-cl:
setx CC clang-cl
setx CXX clang-cl

Note that you may need to reopen the terminal for the environment variables to be available (setx always requires this).

§Pre-built

There is a pre-built release of this crate, zng-view-prebuilt, it works as a drop-in replacement

In the Cargo.toml file:

zng-view-prebuilt = "0.1"

The pre-built crate includes the "software" and "ipc" features, in fact ipc is required, even for running on the same process, you can also configure where the pre-build library is installed, see the zng-view-prebuilt documentation for details.

The pre-build crate does not support extensions.

§API Extensions

This implementation of the view API provides these extensions:

  • "zng-view.webrender_debug": { flags: DebugFlags, profiler_ui: String }, sets Webrender debug flags.
    • The zng-wgt-webrender-debug implements a property that uses this extension.
  • "zng-view.prefer_angle": bool, on Windows, prefer ANGLE(EGL) over WGL if the libEGL.dll and libGLESv2.dll libraries can by dynamically loaded. The extend-view example demonstrates this extension.

You can also inject your own extensions, see the extensions module for more details.

§Crate

This crate is part of the zng project.

§Cargo Features

This crate provides 5 feature flags, 2 enabled by default.

§"ipc"

Enables pre-build and init as view-process.

If this is enabled all communication with the view is serialized/deserialized, even in same-process mode.

Only enables in cfg(not(target_os = "android")) builds.

Enabled by default.

§"software"

Enables software renderer fallback.

If enabled and a native OpenGL 3.2 driver is not available the swgl software renderer is used.

Enabled by default.

§"bundle_licenses"

Bundle third party licenses.

Needs cargo-about and Internet connection during build.

Not enabled by default. Note that "view_prebuilt" always bundles licenses.

§"android_game_activity"

Standard Android backend that requires a build system that can compile Java or Kotlin and fetch Android dependencies.

See https://docs.rs/winit/latest/winit/platform/android/ for more details.

§"android_native_activity"

Basic Android backend that does not require Java.

See https://docs.rs/winit/latest/winit/platform/android/ for more details.

Re-exports§

Modules§

Macros§

  • view_process_extension
    Register a FnOnce(&mut ViewExtensions) closure to be called on view-process init to inject custom API extensions.

Functions§