wolfenrain · wolfenrain · May 17, 2022 · May 17, 2022 · May 17, 2022 · May 17, 2022
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Very Good Ventures
+Copyright (c) 2022 Jochum van der Ploeg
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

@@ -1,172 +1,53 @@
-# Umbra
-
-![coverage][coverage_badge]
-[![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link]
-[![License: MIT][license_badge]][license_link]
-
-Generated by the [Very Good CLI][very_good_cli_link] 🤖
-
-Umbra, visual editor for shaders in Flutter.
+<h1 align="center">
+Umbra
+</h1>
+
+<p align="center">
+<a href="https://github.com/wolfenrain/umbra/actions"><img src="https://github.com/wolfenrain/umbra/workflows/umbra/badge.svg" alt="umbra"></a>
+<a href="https://github.com/wolfenrain/umbra/actions"><img src="https://raw.githubusercontent.com/wolfenrain/umbra/main/coverage_badge.svg" alt="coverage"></a>
+<a href="https://pub.dev/packages/very_good_analysis"><img src="https://img.shields.io/badge/style-very_good_analysis-B22C89.svg" alt="style: very good analysis"></a>
+<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-purple.svg" alt="License: MIT"></a>
+<a href="https://github.com/felangel/mason"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Ftinyurl.com%2Fmason-badge" alt="Powered by Mason"></a>
+</p>
 
 ---
 
-## Getting Started 🚀
+The visual editor for shaders in Flutter.
 
-This project contains 3 flavors:
+> **umbra** <sub>/ˈʌmbrə/</sub>
+>
+> _noun_:
+> 1. the fully shaded inner region of a shadow cast by an opaque object, especially the area on  the earth or moon experiencing the total phase of an eclipse.
+> 2. `LITERARY`  
+>   shadow or darkness.  
+>  "an impenetrable umbra seemed to fill every inch of the museum"
 
-- development
-- staging
-- production
+## Packages
 
-To run the desired flavor either use the launch configuration in VSCode/Android Studio or use the following commands:
+| Package                                                                               | Pub                                                                                                      |
+| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| [umbra_core](https://github.com/wolfenrain/umbra/tree/main/packages/umbra_core)       | [![pub package](https://img.shields.io/pub/v/umbra_core.svg)](https://pub.dev/packages/umbra_core)       |
+| [umbra_flutter](https://github.com/wolfenrain/umbra/tree/main/packages/umbra_flutter) | [![pub package](https://img.shields.io/pub/v/umbra_flutter.svg)](https://pub.dev/packages/umbra_flutter) |
+| [umbra_cli](https://github.com/wolfenrain/umbra/tree/main/packages/umbra_cli)         | [![pub package](https://img.shields.io/pub/v/umbra_cli.svg)](https://pub.dev/packages/umbra_cli)         |
 
-```sh
-# Development
-$ flutter run --flavor development --target lib/main_development.dart
-
-# Staging
-$ flutter run --flavor staging --target lib/main_staging.dart
-
-# Production
-$ flutter run --flavor production --target lib/main_production.dart
-```
-
-_\*Umbra works on iOS, Android, Web, and Windows._
-
----
-
-## Running Tests 🧪
-
-To run all unit and widget tests use the following command:
+## Quick start
 
 ```sh
-$ flutter test --coverage --test-randomize-ordering-seed random
-```
+# 🎯 Activate from https://pub.dev
+dart pub global activate umbra_cli
 
-To view the generated coverage report you can use [lcov](https://github.com/linux-test-project/lcov).
-
-```sh
-# Generate Coverage Report
-$ genhtml coverage/lcov.info -o coverage/
-
-# Open Coverage Report
-$ open coverage/index.html
-```
-
----
-
-## Working with Translations 🌐
-
-This project relies on [flutter_localizations][flutter_localizations_link] and follows the [official internationalization guide for Flutter][internationalization_link].
-
-### Adding Strings
-
-1. To add a new localizable string, open the `app_en.arb` file at `lib/l10n/arb/app_en.arb`.
-
-```arb
-{
-    "@@locale": "en",
-    "counterAppBarTitle": "Counter",
-    "@counterAppBarTitle": {
-        "description": "Text shown in the AppBar of the Counter Page"
-    }
-}
-```
+# 🚀 Install umbra dependencies
+umbra install-deps
 
-2. Then add a new key/value and description
+# 🕶️ Create your first shader
+umbra create hello_world
 
-```arb
-{
-    "@@locale": "en",
-    "counterAppBarTitle": "Counter",
-    "@counterAppBarTitle": {
-        "description": "Text shown in the AppBar of the Counter Page"
-    },
-    "helloWorld": "Hello World",
-    "@helloWorld": {
-        "description": "Hello World Text"
-    }
-}
+# 📦 Compile your first shader to a Dart file
+umbra generate dart shaders/hello_world.glsl --output lib/shaders/
 ```
 
-3. Use the new string
+## Documentation
 
-```dart
-import 'package:umbra/l10n/l10n.dart';
-
-@override
-Widget build(BuildContext context) {
-  final l10n = context.l10n;
-  return Text(l10n.helloWorld);
-}
-```
-
-### Adding Supported Locales
-
-Update the `CFBundleLocalizations` array in the `Info.plist` at `ios/Runner/Info.plist` to include the new locale.
-
-```xml
-    ...
-
-    <key>CFBundleLocalizations</key>
-	<array>
-		<string>en</string>
-		<string>es</string>
-	</array>
-
-    ...
-```
-
-### Adding Translations
-
-1. For each supported locale, add a new ARB file in `lib/l10n/arb`.
-
-```
-├── l10n
-│   ├── arb
-│   │   ├── app_en.arb
-│   │   └── app_es.arb
-```
-
-2. Add the translated strings to each `.arb` file:
-
-`app_en.arb`
-
-```arb
-{
-    "@@locale": "en",
-    "counterAppBarTitle": "Counter",
-    "@counterAppBarTitle": {
-        "description": "Text shown in the AppBar of the Counter Page"
-    }
-}
-```
-
-`app_es.arb`
-
-```arb
-{
-    "@@locale": "es",
-    "counterAppBarTitle": "Contador",
-    "@counterAppBarTitle": {
-        "description": "Texto mostrado en la AppBar de la página del contador"
-    }
-}
-```
-
-## Updating bricks
-
-When a brick gets changed the templates in `umbra_core` need to be updated, you can use the following command for that:
-
-```shell
-mason bundle -t dart ./bricks/<brick_name> -o packages/umbra_core/lib/src/<path_to_template>
-```
+View the general documentation for writing shaders that are compatible with Umbra [here](https://github.com/wolfenrain/umbra/tree/main/docs).
 
-[coverage_badge]: coverage_badge.svg
-[flutter_localizations_link]: https://api.flutter.dev/flutter/flutter_localizations/flutter_localizations-library.html
-[internationalization_link]: https://flutter.dev/docs/development/accessibility-and-localization/internationalization
-[license_badge]: https://img.shields.io/badge/license-MIT-blue.svg
-[license_link]: https://opensource.org/licenses/MIT
-[very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg
-[very_good_analysis_link]: https://pub.dev/packages/very_good_analysis
-[very_good_cli_link]: https://github.com/VeryGoodOpenSource/very_good_cli
+The CLI documentation can be viewed [here](https://github.com/wolfenrain/umbra/tree/main/packages/umbra_cli).
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Jochum van der Ploeg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -1,40 +1,127 @@
-# umbra_cli
+<h1 align="center">
+Umbra CLI
+</h1>
 
-[![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link]
-[![License: MIT][license_badge]][license_link]
+<p align="center">
+<a href="https://pub.dev/packages/umbra_cli"><img src="https://img.shields.io/pub/v/umbra_cli.svg" alt="Pub"></a>
+<a href="https://github.com/wolfenrain/umbra/actions"><img src="https://github.com/wolfenrain/umbra/workflows/umbra_cli/badge.svg" alt="umbra_cli"></a>
+<a href="https://github.com/wolfenrain/umbra/actions"><img src="https://raw.githubusercontent.com/wolfenrain/umbra/main/packages/umbra_cli/coverage_badge.svg" alt="coverage"></a>
+<a href="https://pub.dev/packages/very_good_analysis"><img src="https://img.shields.io/badge/style-very_good_analysis-B22C89.svg" alt="style: very good analysis"></a>
+<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-purple.svg" alt="License: MIT"></a>
+<a href="https://github.com/felangel/mason"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Ftinyurl.com%2Fmason-badge" alt="Powered by Mason"></a>
+</p>
 
 ---
 
-Command Line Interface for Umbra.
+Umbra CLI allows Flutter developers to create their own shaders and compile them to strongly typed dart files.
 
-## Installing
+## Quick start
 
 ```sh
+# 🎯 Activate from https://pub.dev
 dart pub global activate umbra_cli
+
+# 🚀 Install umbra dependencies
+umbra install-deps
+
+# 🕶️ Create your first shader
+umbra create hello_world
+
+# 📦 Compile your first shader to a Dart file
+umbra generate dart shaders/hello_world.glsl --output lib/shaders/
+```
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+  - [Installation](#installation)
+- [Creating New Shaders](#creating-new-shaders)
+- [Generating Files Based On Shaders](#generating-files-based-on-shaders)
+  - [Dart Files](#dart-files)
+  - [Raw GLSL files](#raw-glsl-files)
+  - [SPIR-V Binaries](#spir-v-binaries)
+## Overview
+
+### Installation
+
+```sh
+# 🎯 Activate from https://pub.dev
+dart pub global activate umbra_cli
+
+# 🚀 Install umbra dependencies
+umbra install-deps
+```
+
+`umbra install-deps` installs all the third party dependencies that the CLI needs to be able to generate the necessary files.
+
+❗ Note: by default it will store these dependencies in `$HOME/.umbra/bin`.
+
+## Creating New Shaders
+
+Create a new shader using the `umbra create` command.
+
+For documentation about writing shaders that are compatible with Umbra, see the [general documentation](https://github.com/wolfenrain/umbra/tree/main/docs).
+
+```sh
+# Create a new shader in the current directory.
+umbra create <SHADER_NAME>
+
+# Create a new shader in a custom path.
+umbra create <SHADER_NAME> --output ./path/to/shader/files
+
+# Create a new shader in a custom path short-hand syntax.
+umbra create <SHADER_NAME> -o ./path/to/shader/files
 ```
 
-## Commands
+## Generating Files Based On Shaders
+
+Generate files based on a Umbra Shader using the `umbra generate` command.
+
+### Dart Files
+
+Generate a Dart file for Flutter that provides a strongly typed interface for the shader.
+
+```sh
+# Generate a Dart file in a custom path.
+umbra generate dart my_shader.glsl --output ./path/to/dart/files
+
+# Generate a Dart file in a custom path short-hand syntax.
+umbra generate dart my_shader.glsl -o ./path/to/dart/files
 
-#### `umbra generate`
+# Generate a Dart file and output it to stdout.
+umbra generate raw my_shader.glsl --output -
+```
 
-Generate files based on a given shader file:
+### Raw GLSL Files
 
-TODO: gif here
+Generate a raw GLSL file that is used internally by Umbra for generating both the Dart files and SPIR-V binaries.
 
-##### Usage
+❗ Note: the output of this command can't be used for generating Dart files or SPIR-V binaries through the Umbra CLI.
 
 ```sh
-# Generate the raw GLSL shader based on the given shader file
-umbra generate raw ./shaders/simple.glsl --output ./shaders/simple_raw.glsl
+# Generate a raw GLSL file in a custom path.
+umbra generate raw my_shader.glsl --output ./path/to/dart/files
 
-# Generate a useable SPIRV file for Flutter based on the given shader file
-umbra generate spirv ./shaders/simple.glsl --output ./assets/shaders
+# Generate a raw GLSL file in a custom path short-hand syntax.
+umbra generate raw my_shader.glsl -o ./path/to/dart/files
 
-# Generate a strongly typed Dart file based on the given shader file
-umbra generate dart ./shaders/simple.glsl --output ./lib/shaders
+# Generate a raw GLSL file and output it to stdout.
+umbra generate raw my_shader.glsl --output -
 ```
 
-[license_badge]: https://img.shields.io/badge/license-MIT-blue.svg
-[license_link]: https://opensource.org/licenses/MIT
-[very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg
-[very_good_analysis_link]: https://pub.dev/packages/very_good_analysis
+### SPIR-V Binaries
+
+Generate a SPIR-V file that can be used as an asset for Flutter.
+
+```sh
+# Generate a SPIR-V binary in a custom path.
+umbra generate spirv my_shader.glsl --output ./path/to/spirv/files
+
+# Generate a SPIR-V binary in a custom path short-hand syntax.
+umbra generate spirv my_shader.glsl -o ./path/to/spirv/files
+
+# Generate a SPIR-V binary and output it to stdout.
+umbra generate spirv my_shader.glsl --output -
+```