mirrors/Graphite
1
0
Fork 0
mirror of https://github.com/GraphiteEditor/Graphite.git synced 2025-08-04 13:30:48 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Update terminology in the docs

Browse source
This commit is contained in:
Keavon Chambers 2021-08-12 00:39:29 -07:00
parent 92953e348b
commit 2367f5e56b
3 changed files with 52 additions and 226 deletions
Download patch file Download diff file Expand all files Collapse all files

16
docs/codebase/README.md
View file

@ -16,19 +16,15 @@ Each depends on its successor in the list. These are used internally but also in
The main modules of the project architecture are outlined below. Some parts describe future features and the directories don't exist yet. **Bold** modules are required for Graphite 0.1 which is purely an SVG editor.
- **Web frontend**: `/frontend/`
Initial GUI for Graphite that will eventually be replaced by a native GUI implementation
- **Graphite Editor (Frontend)**: `/frontend/`
Prototype web-based GUI for Graphite that will eventually be replaced by a native GUI frontend implementation
- **Vue web app**: `src/`
Imports the WASM code and uses Vue props to customize and reuse most GUI components
- **Rust WebAssembly translation layer**: `wasm/`
Wraps the editor client backend and provides an API for the web app to use unburdened by Rust's complex data types that are not supported by JS
- **Editor Client Backend**: `/editor/`
- **Graphite Editor (Backend)**: `/editor/`
Used by a frontend editor client to maintain GUI state and dispatch user events. The official Graphite editor is the primary user, but others software like game engines could embed their own customized editor implementations. Depends on Graphene.
- **Graphene Document Graph Engine**: `/graphene/`
- **Graphene (Document Graph Engine)**: `/graphene/`
A stateless library for updating Graphite design document (GDD) files. The official Graphite CLI and editor client backend are the primary users, but this library is intended to be useful to any application that wants to link the library for the purpose of updating GDD files by sending edit operations. Optionally depends on Charcoal if rendering is required.
- **Charcoal Asset Render Engine**: `/charcoal/`
A stateless library (with the help of in-memory and/or on-disk caches for performance) for rendering Graphite's render graph (GRD) files. The official Graphite CLI and Graphene are the primary users, but this library is intended to be useful to any application that wants to link the library for the purpose of rendering Graphite's render graphs. For example, games can link the library and render procedural textures with customizable parametric input values.
## Architecture diagram
Take this [Architecture Overview](architecture-overview.nomnoml) diagram and paste it into the [Nomnoml](https://nomnoml.com/) diagram editor. We'll set up a better way to render Nomnoml diagrams when we have a proper home for this documentation.
- **Charcoal (Asset Render Engine)**: `/charcoal/`
A stateless library (with the help of in-memory and/or on-disk caches for performance) for rendering Graphite's asset graph (GDA) files. The official Graphite CLI and Graphene are the primary users, but this library is intended to be useful to any application that wants to link the library for the purpose of rendering Graphite's asset graphs. For example, games can link the library and render procedural textures with customizable parametric input values.

169
docs/codebase/architecture-overview.nomnoml
View file

@ -1,169 +0,0 @@
#spacing: 120
#arrowSize: 0.5
#leading: 1.5
#gravity: 1
#direction: down
#bendSize: 0.2
#.hdiagram: visual=note direction=right title=bold
#.vdiagram: visual=note direction=down title=bold
#.client: visual=roundrect fill=lightgreen title=bold
#.editor: fill=lightblue title=bold
#.document: fill=darkorange title=bold
#.renderer: fill=gold title=bold
// Clients and Core Libraries
[<hdiagram> Clients and Core Libraries - Usage Overview|
[<client> Frontend Editor Client]
[<client> Headless Editor Client]
[<client> Application Client
(like a game engine or game that renders .grd graphs at runtime)]
[<editor> Editor Core Library]
[<document> Document Core Library]
[<renderer> Renderer Core Library]
[Frontend Editor Client] Depends On -> [Editor Core Library]
[Editor Core Library] Depends On -> [Document Core Library]
[Headless Editor Client] Depends On -> [Document Core Library]
[Document Core Library] Depends On -> [Renderer Core Library]
[Application Client] Depends On -> [Renderer Core Library]
]
[<vdiagram> Clients and Core Libraries - Major Modules|
// Client
[<client> Frontend Implementation|
One of many possible frontend implementations,
such as the native or web client.
]
[<client> CLI Implementation|
A possible text-based CLI program that
wraps Graphite Document. Users can
pass a .gdd document and operation to
add to the document history by saving
to the supplied .gdd file. Users can also
pass a .gdd document and request a
render. Caches are saved to disk.
]
// Editor
[<editor> Dispatcher|
Convert all events from the frontend into Actions
and Operations. Actions are diffs to update state
stores. Operations are history events in a .gdd
file. Operations and document-specific Actions
include the document ID in the call.
]
[Dispatcher] --> Set New Bounds [<renderer> (Backchannel) To: Scheduler]
[Dispatcher] Send Responses <-> Operations [Design Document Maintainer]
[CLI Implementation] -> Send CLI Arguments [Design Document Maintainer]
[<editor> State Stores|
[<editor> Open Documents State Store|
For each open document:|
[<state> Pan and zoom canvas bounds]|
[<state> Selected layers]
]
[<editor> Editor State Store|
[<state> Panel Layout]|
[<state> Working Colors]|
[<state> Active Tool]|
[<state> Tool Options]|
[<state> Modifier Key Input]|
[<state> Currently Hovered Panel]
]
]
[<editor> Tool State Machine|
List the possible operations in current context
]
[Tool State Machine] <:- [State Stores]
[Tool State Machine] -> Send Responses & Operations [Dispatcher]
[Frontend Implementation] Send Responses <-> Send Events [Dispatcher]
[Dispatcher] <:-> Send Actions [State Stores]
[<renderer> (Backchannel) From: Final Render Assembler] --> Send Responses with Rendered Viewport [Dispatcher]
// Document
[<document> Design Document Maintainer|
Process each operation and apply changes to the given document's
operation chain. Consolidate changes where possible by modifying
the previous operation if it's the same as this one and append partial
updates to operations from in-progress interactive tools.
]
[Design Document Maintainer] -> Send Design Document Diff [Render Graph Maintainer]
[Design Document Maintainer] <:-> Write Updated GDD [Open Documents File Store]
[<document> Render Graph Maintainer|
Bake operations into a complete graph including history references.
Starting from the beginning of document history, each operation
modifies the graph in a specific way. If an operation creates a node
that references this point in history, duplicate the current graph pieces
between the live graph and each additional history reference so
changed nodes in history are "ghost variants" living in the live graph.
]
[Render Graph Maintainer] <:-> Write Updated GRD [Open Documents File Store]
[Render Graph Maintainer] -> Send Render Graph [Scheduler]
[<document>Open Documents File Store|
Kept in-memory or written to disk.|
For each open document:|
[<state> Design Document (.gdd)]|
[<state> Render Graph (.grd)]
]
// Renderer
[<renderer> Scheduler|
Manage a thread pool and GPU time. Perform progressive enhancement
and speculative tile rendering. Request re-render of dirtied document within
bounds and stitch them over dirty raster cache tiles. Maintain interactive
responsiveness by targeting a minimum framerate and picking a requisite
render quality level at all times. Precompute nodes downstream of changes
when there is spare CPU thread pool and GPU time. Primary purpose is to
keep the Precompute and Raster Tile caches up-to-date with minimal
onscreen latency. Also notifies the Final Render Assembler when the cache
tiles for the root document visible in bounds have finished being updated.
]
[Scheduler] Set New Bounds <-- [<editor> (Backchannel) From: Dispatcher]
[Scheduler] -> Rasterize Tiles [Node Rasterizer]
[Scheduler] <:-> Write Dirty Status [Node Cache Manager]
[Scheduler] -> Invoke [Final Render Assembler]
[<renderer> Node Cache Manager|
Purges old or less useful cached data
as necessary.|
[<state> Precompute Node Cache|
Prepare data for rasterization step.
Evaluate algorithms (CPU or GPU).
Changes when upstream changes.
]|
[<state> Raster Tile Node Cache|
Must be fast, fragment shader only.
Only reevaluate downstream.
Reuse when panning.
]
]
[Node Cache Manager] -:> [Final Render Assembler]
[<renderer> Node Rasterizer|
Rasterize and update the cache for a specified node
given a preferred bounds (but it can give a different
sized output), resolution, and quality level.
]
[Node Rasterizer] <:-> Write Tiles [Node Cache Manager]
[<renderer> Final Render Assembler|
Look up the rasterized cached tiles from
the document root and assemble them into
an image for live display by the frontend.
Operates when woken up by the scheduler
when root tiles or render bounds are updated.
]
[Final Render Assembler] --> Send Rendered Viewport to Client [<client> (Backchannel) To: Frontend Implementation]
]

93
docs/editor/1-overview.md
View file

@ -8,64 +8,63 @@ TODO
TODO: Add more to make a comprehensive list, finish writing definitions, separate into categories, alphabetize
- Asset
A *GDD* or *GRD* file. Can be shared and *embedded* in another *layer graph*. Useful for providing custom *nodes* that perform some useful functionality. Tangible examples include custom procedural effects, shape generators, and image filters. Many of the Graphite editor's built-in *layers* are also assets that provide useful functionality through a group of nodes rather than being implemented directly in code. The *Asset Manager* panel helps maintain these assets from various sources. The *Asset Store* can be used to share and sell assets for easily inclusion in projects.
- Document
A design source file created and edited in the Graphite editor. When saved to disk as *GDD files* (Graphite Design Document), they are one of the two types of *assets*. Documents can be included as *layers* inside other documents, and in doing so they take the form of *groups*. The *layer graph* contents of a *group* actually belong to the *embedded* document's *subgraph*. Because a document is a *group* which is a *layer* in the *layer graph*, documents have *properties* such as the *frames* in the *canvas*. Documents are composed of a layer graph, a defined set of properties of set *data types* that are *imported* and *exported*, and the *properties* of the *root layer*.
- Render graph
A read-only "compiled" *document* in a format that is immediately ready for rendering. When saved to disk as *GRD files* (Graphite Render Data), they are one of the two types of *assets*. The Graphite editor internally maintains a render graph based on the open document in order to display the *canvas* live in the *viewport*, but this can also be saved to disk for the purposes of sharing as an *asset*.
- GDD file
Graphite Design Document. A binary serialization of a *document* source file. The format includes a chain of *operations* that describe changes to the *layer graph* and the *properties* of *layers* throughout the history of the document since its creation. It also stores certain metadata and *embedded* file data. GDD files, along with *GRD files*, represent *assets* when shared. Because GDD files are editable (unlike *GRD files*), the *layers* of GDD *assets* may be expanded in the layer graph to reveal and modify their contents using a copy-on-write scheme stored to the *asset's* *layer*.
- GRD file
Graphite Render Data. A binary serialization of a *render graph* file. The format includes a single directed acyclic graph (DAG) compiled from the *layer graph* of a *document* as well as certain *properties* of set *data types* that are *imported* and *exported*. GRD files, along with *GDD files*, represent *assets* when shared. Because GRD files are read-only and can't be edited (unlike *GDD files*), the *layers* of GRD *assets* do not offer an ability to be expanded in the layer graph. GRD files are useful for sharing *assets* when their authors do not wish to provide the source *documents* used for their authoring. They are also the input format included in games that utilize *Charcoal* to render graphical content at runtime, as well as similar applications like headless renderers on web servers and image processing pipelines.
- Window
- Main window
- Popout window
- Title bar
- Status bar
- Workspace
- ## Document
A design source file created and edited in the Graphite editor. Saved to disk as a Graphite Design Document in a *GDD file*. Documents can be included as *layers* inside other documents, and in doing so they take the form of *groups*. The *layer graph* contents of a *group* actually belong to the *embedded* document's *subgraph*. Because a document is a *group* which is a *layer* in the *layer graph*, documents have *properties* such as the *frames* in the *canvas*. Documents are composed of a layer graph, a defined set of properties of set *data types* that are *imported* and *exported*, and the *properties* of the *root layer*.
- ## Asset
A portable mechanism for distributing a "compiled" Graphite *document* in a format that is immediately ready for rendering. Saved to disk as a Graphite Digital Asset in a *GDA file*. Assets are created by "flattening" a *document's* complex, nested *layer graph* structure into a single, simple directed acyclic graph (DAG). The Graphite editor internally maintains an asset version of any open *document* in order to draw the *canvas* live in the *viewport*. An asset also includes certain exposed *properties* of specified *data types* that are *imported* and *exported*, as defined by the asset's author in the source *document's* *layer graph*. They can be shared and *embedded* in another *layer graph* as a black box (meaning it can't be expanded to reveal or edit its interior graph), as compared to *embedded* *documents* from *GDD files* which are white boxes (they can be expanded to reveal their *subgraph* which can be edited). Assets are helpful for defining custom *nodes* that perform some useful functionality. Tangible examples include custom procedural effects, shape generators, and image filters. Many of the Graphite editor's own built-in *nodes* are actually assets rather than being implemented directly in code. The *Asset Manager* panel helps maintain these assets from various sources. The *Asset Store* can be used to share and sell assets for easy inclusion in other projects.
- ## GDD file
Graphite Design Document. A binary serialization of a *document* source file. The format includes a chain of *operations* that describe changes to the *layer graph* and the *properties* of *layers* throughout the history of the document since its creation. It also stores certain metadata and the raw data of *embedded* files. Because GDD files are editable (unlike *GDA files*), the *layers* of GDD files imported into another *document* may be expanded in its *layer graph* to reveal and modify their contents using a copy-on-write scheme stored to the *asset's* *layer*.
- ## GDA file
Graphite Digital Asset. A binary serialization of an *asset* file. Because GDA files are read-only and can't be edited (unlike *GDD files*), the *layers* created from *assets* do not offer an ability to be expanded in the *layer graph* of a *document* that *embeds* them. GDA files are useful for sharing *assets* when their authors do not wish to provide the source *documents* to author them. *DGA files* are also the input format included in games that utilize the *Graphite Renderer Core Library* to render graphical content at runtime, as well as similar applications like headless renderers on web servers and image processing pipelines.
- ## Window
- ## Main window
- ## Popout window
- ## Title bar
- ## Status bar
- ## Workspace
The part of the Graphite editor's UI that houses the *panels* in a *window*. The workspace occupies the large space below the *title bar* and above the *status bar* of the *main window*. It occupies the entirety of *popout windows* (window buttons are added in the *tab bar*).
- Workspace layout
- ## Workspace layout
The specific configuration of panels in the *main window* and any *popout windows*. Workspace layout presets are provided by the Graphite editor and users may customize and save their own.
- Tab bar
- ## Tab bar
The bar at the top of a *panel group* which includes a clickable tab for each panel that is docked there. Each tab bar has at least one tab and one active tab.
- Active tab
- ## Active tab
The one tab in a *tab bar* that is currently active. The user can click any inactive tab to make it become the active tab. The active tab shows the *panel content* beneath it unless it is a *folded panel*.
- Folded panel
- ## Folded panel
A shrunken *panel* showing only the *tab bar*. A *panel* consists of the *tab bar* and *panel body* except when the latter is folded away. The user may click the *active tab* to fold and restore a panel, however a panel cannot be folded if there are no other unfolded panels in its column.
- Panel
- Panel body
- Options bar
- ## Panel
- ## Panel body
- ## Options bar
The bar that spans horizontally across the top of a *panel* (located under the *tab bar*) which displays options related to the *panel*.
- Viewport
- ## Viewport
The area that takes up the main space in a *panel* (located beneath the *options bar*) which displays the primary content of the *panel*.
- Shelf
- ## Shelf
The bar that spans vertically along the left side of some *panels* (located left of the *viewport*) which displays a catalog of available items, such as document editing *tools* or common *nodes*.
- Tool
- ## Tool
An instrument for interactively editing *documents* through a collection of related behavior. Each tool puts the editor into a mode that provides the ability to perform certain *operations* on the document interactively. Each *operation* is run based on the current context of mouse and modifier buttons, key presses, tool options, selected layers, editor state, and document state. The *operations* that get run are appended to the document history and update the underlying *layer graph* in real time.
- Canvas
- ## Canvas
The infinite coordinate system that shows the visual output of an open *document* at the current zoom level and pan position. It is drawn in the document panel's *viewport* within the area inside the scroll bars on the bottom/right edges and the *rulers* on the top/left edges. The canvas can be panned and zoomed in order to display all or part of the artwork in any *frames*. A canvas has a coordinate system spanning infinitely in all directions with an origin always located at the top left of the primary *frame*. The purpose of an infinite canvas is to offer a convenient editing experience when there is no logical edge to the artwork, for example a loosely-arranged board of logo design concepts, a mood board, or whiteboard-style notes.
- Frame
- ## Frame
An area inside a *canvas* that provides rectangular bounds to the artwork contained within, as well as default bounds for an exported image. This is also called an "artboard" in some other software. The *crop tool* adjusts the bounds and placement of frames in the *document* and each frame is stored in a "frame list" property of the *root layer*. When there is at least one frame, the infinite *canvas* area outside any frame displays a configurable background color. Artwork can be placed outside of a frame but it will appear mostly transparent. The purpose of using one frame is to provide convenient cropping to the edges of the artwork, such as a single digital painting or photograph. The purpose of using multiple frames is to work on related artwork with separate bounds, such as the layout for a book.
- Layer graph
- ## Layer graph
A (directed acyclic) graph structure composed of *layers* with *connections* between their input and output *ports*. This is commonly referred to as a "node graph" in other software, but Graphite's layer graph is more suited towards layer-based compositing compared to traditional compositor node graphs.
- Node
- ## Node
A definition of a *layer*. A node is a graph "operation" or "function" that receives input and generates deterministic output.
- Layer
- ## Layer
Any instance of a *node* that lives in the *layer graph*. Layers (usually) take input data, then they transform it or synthesize new data, then they provide it as output. Layers have *properties* as well as exposed input and output *ports* for sending and receiving data.
- Root layer
- Group
- Raster
- Vector
- Mask
- Data type
- Subgraph
- Port
- Connection
- Core Libraries
- Editor client backend
- Graphene
- Charcoal
- Trace
- Path
- Shape
- ## Root layer
- ## Group
- ## Raster
- ## Vector
- ## Mask
- ## Data type
- ## Subgraph
- ## Port
- ## Connection
- ## Core Libraries
- ## Graphite Editor (Frontend)
- ## Graphite Editor (Backend)
- ## Graphene (Document Graph Engine)
- ## Charcoal (Asset Render Engine)
- ## Trace
- ## Path
- ## Shape