blob: b1f65c73c73d6a93f03058453396824fbe6e73c7 [file] [log] [blame] [view]
# 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](https://fuchsia.dev/fuchsia-src/getting_started#configure-and-build-fuchsia)
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](https://rive.app) 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