Skip to content

Commit

Permalink
rename "compositor"/"surface" to "canvaskit"/"html"; document convent…
Browse files Browse the repository at this point in the history 
…ions (flutter#20579)

* rename "compositor"/"surface" to "canvaskit"/"html"; document conventions
  • Loading branch information
@yjbanov
yjbanov authored Aug 18, 2020
1 parent 35640af commit 7f858aa
Show file tree
Hide file tree
Showing 59 changed files with 183 additions and 121 deletions.
112 changes: 56 additions & 56 deletions ci/licenses_golden/licenses_flutter
View file
Original file line number Diff line number Diff line change
Expand Up @@ -426,42 +426,69 @@ FILE: ../../../flutter/lib/web_ui/lib/src/engine/bitmap_canvas.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/browser_detection.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/browser_location.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvas_pool.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/canvas.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/canvaskit_api.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/canvaskit_canvas.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/color_filter.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/embedded_views.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/fonts.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/image.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/image_filter.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/initialization.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/layer.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/layer_scene_builder.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/layer_tree.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/mask_filter.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/n_way_canvas.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/painting.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/path.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/path_metrics.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/picture.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/picture_recorder.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/platform_message.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/raster_cache.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/rasterizer.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/shader.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/skia_object_cache.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/surface.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/text.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/util.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/vertices.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/canvaskit/viewport_metrics.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/clipboard.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/color_filter.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/canvas.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/canvas_kit_canvas.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/canvaskit_api.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/color_filter.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/embedded_views.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/fonts.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/image.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/image_filter.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/initialization.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/layer.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/layer_scene_builder.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/layer_tree.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/mask_filter.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/n_way_canvas.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/painting.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/path.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/path_metrics.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/picture.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/picture_recorder.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/platform_message.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/raster_cache.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/rasterizer.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/shader.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/skia_object_cache.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/surface.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/text.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/util.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/vertices.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/compositor/viewport_metrics.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/dom_canvas.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/dom_renderer.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/engine_canvas.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/frame_reference.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/history.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/backdrop_filter.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/canvas.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/clip.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/debug_canvas_reuse_overlay.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/image_filter.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/offset.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/opacity.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/painting.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/path/conic.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/path/cubic.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/path/path.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/path/path_metrics.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/path/path_ref.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/path/path_to_svg.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/path/path_utils.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/path/path_windings.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/path/tangent.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/picture.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/platform_view.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/recording_canvas.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/render_vertices.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/scene.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/scene_builder.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/shader.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/surface.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/surface_stats.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html/transform.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/html_image_codec.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/keyboard.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/mouse_cursor.dart
Expand Down Expand Up @@ -489,33 +516,6 @@ FILE: ../../../flutter/lib/web_ui/lib/src/engine/services/message_codec.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/services/message_codecs.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/services/serialization.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/shadow.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/backdrop_filter.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/canvas.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/clip.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/debug_canvas_reuse_overlay.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/image_filter.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/offset.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/opacity.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/painting.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/path/conic.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/path/cubic.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/path/path.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/path/path_metrics.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/path/path_ref.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/path/path_to_svg.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/path/path_utils.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/path/path_windings.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/path/tangent.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/picture.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/platform_view.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/recording_canvas.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/render_vertices.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/scene.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/scene_builder.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/shader.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/surface.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/surface_stats.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/surface/transform.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/test_embedding.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/text/font_collection.dart
FILE: ../../../flutter/lib/web_ui/lib/src/engine/text/line_break_properties.dart
Expand Down
62 changes: 62 additions & 0 deletions lib/web_ui/CODE_CONVENTIONS.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Web-specific coding conventions and terminology

Here you will find various naming and structural conventions used in the Web
engine code. This is not a code style guide. For code style refer to
[Flutter's style guide][1]. This document does not apply outside the `web_ui`
directory.

## CanvasKit Renderer

All code specific to the CanvasKit renderer lives in `lib/src/engine/canvaskit`.

CanvasKit bindings should use the exact names defined in CanvasKit's JavaScript
API, even if it violates Flutter's style guide, such as function names that
start with a capital letter (e.g. "MakeSkVertices"). This makes it easier to find
the relevant code in Skia's source code. CanvasKit bindings should all go in
the `canvaskit_api.dart` file.

Files and directories should use all-lower-case "canvaskit", without
capitalization or punctuation (such as "canvasKit", "canvas-kit", "canvas_kit").
This is consistent with Skia's conventions.

Variable, function, method, and class names should use camel case, i.e.
"canvasKit", "CanvasKit".

In documentation (doc comments, flutter.dev website, markdown files,
blog posts, etc) refer to Flutter's usage of CanvasKit as "CanvasKit renderer"
(to avoid confusion with CanvasKit as the standalone library, which can be used
without Flutter).

Classes that wrap CanvasKit classes should replace the `Sk` class prefix with
`Ck` (which stands for "CanvasKit"), e.g. `CkPaint` wraps `SkPaint`, `CkImage`
wraps `SkImage`.

## HTML Renderer

All code specific to the HTML renderer lives in `lib/src/engine/html`.

In documentation (doc comments, flutter.dev website, markdown files,
blog posts, etc) refer to Flutter's HTML implementation as "HTML renderer". We
include SVG, CSS, and Canvas 2D under the "HTML" umbrella.

The implementation of the layer system uses the term "surface" to refer to
layers. We rely on persisting the DOM information across frames to gain
efficiency. Each concrete implementation of the `Surface` class should start
with the prefix `Persisted`, e.g. `PersistedOpacity`, `PersistedPicture`.

## Semantics

The semantics (accessibility) code is shared between CanvasKit and HTML. All
semantics code lives in `lib/src/engine/semantics`.

## Text editing

Text editing code is shared between CanvasKit and HTML, and it lives in
`lib/src/engine/text_editing`.

## Common utilities

Small common utilities do not need dedicated directories. It is OK to put all
such utilities in `lib/src/engine` (see, for example, `alarm_clock.dart`).

[1]: https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo
112 changes: 56 additions & 56 deletions lib/web_ui/lib/src/engine.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,43 +27,70 @@ part 'engine/assets.dart';
part 'engine/bitmap_canvas.dart';
part 'engine/browser_detection.dart';
part 'engine/browser_location.dart';
part 'engine/canvaskit/canvas.dart';
part 'engine/canvaskit/canvaskit_canvas.dart';
part 'engine/canvaskit/canvaskit_api.dart';
part 'engine/canvaskit/color_filter.dart';
part 'engine/canvaskit/embedded_views.dart';
part 'engine/canvaskit/fonts.dart';
part 'engine/canvaskit/image.dart';
part 'engine/canvaskit/image_filter.dart';
part 'engine/canvaskit/initialization.dart';
part 'engine/canvaskit/layer.dart';
part 'engine/canvaskit/layer_scene_builder.dart';
part 'engine/canvaskit/layer_tree.dart';
part 'engine/canvaskit/mask_filter.dart';
part 'engine/canvaskit/n_way_canvas.dart';
part 'engine/canvaskit/path.dart';
part 'engine/canvaskit/painting.dart';
part 'engine/canvaskit/path_metrics.dart';
part 'engine/canvaskit/picture.dart';
part 'engine/canvaskit/picture_recorder.dart';
part 'engine/canvaskit/platform_message.dart';
part 'engine/canvaskit/raster_cache.dart';
part 'engine/canvaskit/rasterizer.dart';
part 'engine/canvaskit/shader.dart';
part 'engine/canvaskit/skia_object_cache.dart';
part 'engine/canvaskit/surface.dart';
part 'engine/canvaskit/text.dart';
part 'engine/canvaskit/util.dart';
part 'engine/canvaskit/vertices.dart';
part 'engine/canvaskit/viewport_metrics.dart';
part 'engine/canvas_pool.dart';
part 'engine/clipboard.dart';
part 'engine/color_filter.dart';
part 'engine/compositor/canvas.dart';
part 'engine/compositor/canvas_kit_canvas.dart';
part 'engine/compositor/canvaskit_api.dart';
part 'engine/compositor/color_filter.dart';
part 'engine/compositor/embedded_views.dart';
part 'engine/compositor/fonts.dart';
part 'engine/compositor/image.dart';
part 'engine/compositor/image_filter.dart';
part 'engine/compositor/initialization.dart';
part 'engine/compositor/layer.dart';
part 'engine/compositor/layer_scene_builder.dart';
part 'engine/compositor/layer_tree.dart';
part 'engine/compositor/mask_filter.dart';
part 'engine/compositor/n_way_canvas.dart';
part 'engine/compositor/path.dart';
part 'engine/compositor/painting.dart';
part 'engine/compositor/path_metrics.dart';
part 'engine/compositor/picture.dart';
part 'engine/compositor/picture_recorder.dart';
part 'engine/compositor/platform_message.dart';
part 'engine/compositor/raster_cache.dart';
part 'engine/compositor/rasterizer.dart';
part 'engine/compositor/shader.dart';
part 'engine/compositor/skia_object_cache.dart';
part 'engine/compositor/surface.dart';
part 'engine/compositor/text.dart';
part 'engine/compositor/util.dart';
part 'engine/compositor/vertices.dart';
part 'engine/compositor/viewport_metrics.dart';
part 'engine/dom_canvas.dart';
part 'engine/dom_renderer.dart';
part 'engine/engine_canvas.dart';
part 'engine/frame_reference.dart';
part 'engine/history.dart';
part 'engine/html/backdrop_filter.dart';
part 'engine/html/canvas.dart';
part 'engine/html/clip.dart';
part 'engine/html/debug_canvas_reuse_overlay.dart';
part 'engine/html/image_filter.dart';
part 'engine/html/offset.dart';
part 'engine/html/opacity.dart';
part 'engine/html/painting.dart';
part 'engine/html/path/conic.dart';
part 'engine/html/path/cubic.dart';
part 'engine/html/path/path.dart';
part 'engine/html/path/path_metrics.dart';
part 'engine/html/path/path_ref.dart';
part 'engine/html/path/path_to_svg.dart';
part 'engine/html/path/path_utils.dart';
part 'engine/html/path/path_windings.dart';
part 'engine/html/path/tangent.dart';
part 'engine/html/picture.dart';
part 'engine/html/platform_view.dart';
part 'engine/html/recording_canvas.dart';
part 'engine/html/render_vertices.dart';
part 'engine/html/scene.dart';
part 'engine/html/scene_builder.dart';
part 'engine/html/shader.dart';
part 'engine/html/surface.dart';
part 'engine/html/surface_stats.dart';
part 'engine/html/transform.dart';
part 'engine/html_image_codec.dart';
part 'engine/keyboard.dart';
part 'engine/mouse_cursor.dart';
Expand Down Expand Up @@ -91,33 +118,6 @@ part 'engine/services/message_codec.dart';
part 'engine/services/message_codecs.dart';
part 'engine/services/serialization.dart';
part 'engine/shadow.dart';
part 'engine/surface/backdrop_filter.dart';
part 'engine/surface/canvas.dart';
part 'engine/surface/clip.dart';
part 'engine/surface/debug_canvas_reuse_overlay.dart';
part 'engine/surface/image_filter.dart';
part 'engine/surface/offset.dart';
part 'engine/surface/opacity.dart';
part 'engine/surface/painting.dart';
part 'engine/surface/path/conic.dart';
part 'engine/surface/path/cubic.dart';
part 'engine/surface/path/path.dart';
part 'engine/surface/path/path_metrics.dart';
part 'engine/surface/path/path_ref.dart';
part 'engine/surface/path/path_to_svg.dart';
part 'engine/surface/path/path_utils.dart';
part 'engine/surface/path/path_windings.dart';
part 'engine/surface/path/tangent.dart';
part 'engine/surface/picture.dart';
part 'engine/surface/platform_view.dart';
part 'engine/surface/recording_canvas.dart';
part 'engine/surface/render_vertices.dart';
part 'engine/surface/scene.dart';
part 'engine/surface/scene_builder.dart';
part 'engine/surface/shader.dart';
part 'engine/surface/surface.dart';
part 'engine/surface/surface_stats.dart';
part 'engine/surface/transform.dart';
part 'engine/test_embedding.dart';
part 'engine/text/font_collection.dart';
part 'engine/text/line_break_properties.dart';
Expand Down
0 ..._ui/lib/src/engine/compositor/canvas.dart → ...b_ui/lib/src/engine/canvaskit/canvas.dart
View file
File renamed without changes.
Loading

0 comments on commit 7f858aa

Please sign in to comment.