Introduction

Carnelian is a prototype framework for writing Fuchsia modules in Rust.

To build the included samples, use the fx set line below to build the core version of Fuchsia with the necessary additional packages to run either directly on the frame buffer or with scenic using the tiles tool. See these configuration instructions for more details.

fx set core.x64 \
    --with //src/lib/ui/carnelian:examples \
    --with //src/lib/ui/carnelian:carnelian-integration-test \
    --with //src/lib/ui/carnelian:carnelian-fb-integration-test \
    --with //src/lib/ui/carnelian:carnelian-tests \
    --with //src/lib/ui/carnelian:carnelian-layout-tests \
    --release \
    --auto-dir \
    --args=rust_cap_lints='"warn"' \
    --args='core_realm_shards += [ "//src/lib/ui/carnelian:carnelian_examples_shard" ]'
    --cargo-toml-gen

To disable virtcon, add

    --args='dev_bootfs_labels=["//products/kernel_cmdline:virtcon.disable--true"]'

To run an example in virtcon mode, add :virtcon_config to additional_deps for that example in BUILD.gn

Examples

The examples directory contains a set of Carnelian example programs.

Running

To run the examples, use ffx component. The core_realm_shard added above installs a collection into the /core realm that can be used to launch examples.

The basic workflow is:

1. ffx component create /core/carnelian-examples:square-rs fuchsia-pkg://fuchsia.com/spinning-square-rs#meta/spinning-square-rs.cm
2. ffx component start /core/carnelian-examples:square-rs

Note that carnelian-examples is the collection name and must be typed. However, the name of the created component, square-rs above, is user-defined when invoking ffx component create. To run another example, replace spinning-square-rs in the component URL with the example name.

Layout-based Examples

These examples demonstrate using scenes, facets and groups to layout user-interface.

button

This example implements a single button which, when pressed, toggles a rectangle from red to green.

The ‘M’ key on an attached keyboard will cycle the main axis alignment of the row containing the indicators. Pressing ‘C’ will cycle the cross axis alignment of that row. Pressing ‘R’ will cycle the main alignment of the column containing both the button and the indicators.

layout_gallery

This example is a gallery of the existing group layouts as well as housing tests for those layouts.

The ‘M’ key on an attached keyboard will cycle between layouts modes of stack, flex and button, where the button layout is a test version of the layout used by the button example.

For stack, hitting the ‘1’ key cycles the alignment of the stack.

For flex, hitting the ‘1’, ‘2’ and ‘3’ keys cycles the various parameters of the flex layout.

Pressing the ‘D’ key will dump the bounds of the scene's facets for use in test validation.

spinning_square

The original example, now improved to use layout and demonstrate facet draw order.

Press the space bar on an attached keyboard to toggle the square between sharp and rounded corners.

Press the ‘B’ key to move the square backwards in facet draw order, or ‘F’ to move it forwards.

Scene-based Examples

These example demonstrate scenes, but rather than using layout they take responsbility for positioning the facets.

clockface

This example draws a clock face.

font_metrics

This example displays metrics about certain fonts.

gamma

This example demonstrate how Carnelian can be used to produce gamma correct output.

rive

Rive is a file format for animations. This example loads the example from file and displays it. By default it will load juice.riv but the --file command line option can be used to select a different .riv file.

shapes

This example shows how to use pointer input. Press and hold anywhere in the running app to create a random shape. Drag the pointer to move this shape around. Release the pointer to let the shape fall towards the bottom of the screen.

svg

This example loads a vector file in shed format and displays it. Press and hold to drag the image around the screen.

Render-based Examples

These examples use the render mechanism directly, instead of using scenes and facets.

ink

This example demonstrate efficient drawing on devices with stylus support.

png

This example loads a PNG file from disk and displays it. The scene system does not support the post-copy mechanism used to display pixel, rather than vector, data. Eventually pixel data will be supported more directly and this sample can be converted to use scenes.

Tentative Roadmap

1. Flutter-style flex-box layout

Flutter-style flex-box layout

Currently, layout in Carnelian only supports fixed size facets. The next step will be to allow some kinds of facets to be flexibly sized.

Future Areas

Command Handling

Mature application frameworks usually have some mechanism for commands that might apply to multiple items in the view hierarchy to be handled by the most specific first and proceeding to less specific items. This command handling structure can also be used to show/enable menu items if Fuchsia ever has such a menu.

Animation

Design and implement a simple animation facility.

Frequently Asked Questions