How openharmony/graphic_graphic_utils_lite works
This repository is the foundational graphics utility layer for OpenHarmony Lite. It is not an application by itself; it provides the shared data types, math/geometry helpers, 2D drawing primitives, and platform adaptation hooks that higher graphics modules consume.
High-level architecture
The repo is organized as a layered library with two closely related concerns:
1. Utils / graphics common layer
- Shared types and algorithms used across the graphics subsystem.
- Focuses on geometry, transforms, styles, color, pixel formats, timing, memory, and diagram/rasterization primitives.
2. HALS / hardware adaptation layer
- Encapsulates low-level platform and driver-facing capabilities.
- Abstracts framebuffer/GFX access, CPU capability handling, and related platform services.
The architectural boundary is important:
• interfaces/kits/... is the public API surface exposed to higher-level modules such as UI, surface, and WMS.
• interfaces/innerkits/... is the internal cross-module API used between graphics components and the hardware adaptation layer.
• frameworks/... contains the concrete implementations behind those interfaces.
Main subsystems
1) Core graphics utilities
These files implement the foundational value types and helper logic that other rendering code builds on:
• color.cpp, style.cpp — color and styling definitions for drawing.
• rect.h, geometry2d.h, graphic_math.h, trans_affine.h, transform.h — geometry, coordinate transforms, affine transforms, and math utilities.
• pixel_format_utils.cpp — pixel format handling and conversions.
• graphic_buffer.h, image_info.h — image/buffer metadata used by rendering pipelines.
• list.h, vector.h, heap_base.h, mem_api.cpp — container and memory abstraction support.
• graphic_timer.cpp, hal_tick.cpp, hal_cpu.cpp, sys_info.cpp, version.cpp, graphic_performance.cpp — timing, CPU/platform information, performance measurement, and version reporting.
• graphic_log.h, graphic_assert.h — diagnostics and validation.
These are the basic building blocks passed around by the higher-level rendering code.
2) Diagram / 2D rendering pipeline
The frameworks/diagram subtree is the core of the 2D graphics engine implementation. It is split into stages that mirror a typical vector-to-raster rendering flow:
• vertexprimitive/
- Generates geometric primitives such as arcs, Bézier arcs, curves, and path-shortening logic.
- Examples: geometry_arc.cpp, geometry_bezier_arc.cpp, geometry_curves.cpp, geometry_shorten_path.cpp.
• vertexgenerate/
- Produces renderable vertex streams from higher-level geometry.
- Examples: dash and stroke expansion (vertex_generate_dash.cpp, vertex_generate_stroke.cpp).
• depiction/
- Curve depiction logic for generating smooth curve points.
- Example: depict_curve.cpp.
• rasterizer/
- Scanline and antialias rasterization, including clipping.
- Examples: rasterizer_cells_antialias.cpp, rasterizer_scanline_antialias.cpp, rasterizer_scanline_clip.cpp.
• common/
- Shared paint logic for the diagram pipeline.
- Example: paint.cpp.
On the API side, the matching headers under interfaces/kits/gfx_utils/diagram/... expose:
• curve and path primitives,
• dash/stroke generation,
• scanline and rasterizer abstractions,
• span color fill helpers,
• image filter support such as blur.
This subsystem is the most pipeline-like part of the repo: path and curve geometry is transformed into vertices, then into scanlines, then rasterized into pixels using fill/paint logic.
3) Hardware adaptation layer (HALS)
The HALS portion bridges the graphics utilities to the underlying platform and driver stack:
• frameworks/hals/gfx_engines.cpp — abstraction around graphics engine capabilities.
• frameworks/hals/hi_fbdev.cpp — framebuffer/device-facing adaptation.
• interfaces/innerkits/hals/gfx_engines.h, hi_fbdev.h — internal contracts for that layer.
• hal_cpu.cpp, hal_tick.cpp — low-level CPU and tick access used by the rest of the graphics stack.
The README explicitly describes this layer as adapting and encapsulating driver/platform functions such as FrameBuffer, GFX, and SIMD-related support. In architecture terms, it is the boundary between portable graphics code and platform-specific execution.
Data flow through the repo
A typical flow through this library looks like this:
1. Upper modules call public kits APIs
- UI, surface, and WMS use the headers under interfaces/kits/gfx_utils.
- They work with shared types like color, rect, vector, buffer, transform, and image info.
2. Geometry and style are normalized
- Utility code converts application intent into internal representations.
- Transforms, affine matrices, style, and pixel format utilities shape the rendering request.
3. Diagram pipeline expands vector shapes
- Paths and curves are converted into vertex primitives.
- Stroke/dash logic expands outlines.
- Depiction logic smooths curve points.
4. Rasterizer converts geometry to scanlines
- Scanline rasterizers and clipping logic translate vector content into raster-friendly spans.
- Fill helpers in spancolorfill determine how pixels are colored.
5. HALS provides platform execution support
- CPU/tick information, framebuffer access, and graphics-engine hooks connect the rendering logic to the device/platform.
6. Output is consumed by downstream graphics modules
- The repo does not own presentation or window management; it supplies the rendering and support primitives those subsystems rely on.
Key architectural boundaries
Public vs internal API
• interfaces/kits/... is the stable, external-facing contract.
• interfaces/innerkits/... is for internal module-to-module use and hardware adaptation.
• This separation is important for understanding what is meant to be consumed by other repos versus what is implementation detail.
Portable logic vs platform-specific logic
• Most of frameworks/ is portable C++ utility and rendering code.
• The HALS files are the thin adaptation boundary to hardware/platform facilities.
Shared primitives vs rendering pipeline
• Core types such as color, rect, vector, transform, and graphic_buffer are reusable data contracts.
• The diagram subtree is the actual rendering engine pipeline that consumes those contracts.
Build and packaging
• The repo is built with GN through the OpenHarmony build system (hb build graphic_utils_lite).
• The output is a shared-library style component used by the broader graphics stack.
• The presence of bundle.json, BUILD.gn, and OAT.xml indicates it is packaged as part of the OpenHarmony component ecosystem rather than as a standalone executable.
Testing
The test/ directory contains unit tests for the core value and math layers:
• color
• geometry2d
• graphic_math
• graphic_timer
• list
• rect
• style
• transform
• vector
These tests validate the foundational behaviors that higher rendering layers depend on.
How to read this repo in an architecture diagram
If you are drawing the architecture, the cleanest structure is:
• Top consumers: UI, surface, WMS
• Public API boundary: interfaces/kits
• Internal API boundary: interfaces/innerkits
• Implementation layer: frameworks
- core utilities
- diagram/rendering pipeline
- HALS adaptation
• Platform/driver side: framebuffer, GFX, CPU/tick/SIMD support
• Validation layer: test
In short, this repo is the graphics subsystem’s shared utility and adaptation foundation: portable math/data/rendering primitives in the middle, thin hardware abstraction at the bottom, and stable APIs exposed at the top for other graphics-related modules.
Main entry points: gfx_utils Public gfx utils · diagram Diagram API · vertexgenerate Vertex generation · test Unit tests
Components 16
API surface
Public kits APIs and internal contracts exposed to other graphics modules.
- Public gfx utils · Stable public graphics utility headers for shared types, math, containers, and diagnostics.
interfaces/kits/gfx_utils - Diagram API · Public 2D drawing, path, scanline, fill, and image-filter interfaces.
interfaces/kits/gfx_utils/diagram - Inner HAL API · Internal interfaces for timers, CPU helpers, threading primitives, and HALS adapters.
interfaces/innerkits
Implementations
Concrete utility, rendering, and HALS code under frameworks/.
- Core types · Color, rect, style, image, buffer, and other common data contracts.
frameworks - Geometry math · 2D geometry, affine transforms, coordinate math, and general transform utilities.
frameworks - Containers / memory · Container and memory abstraction utilities used by graphics code.
frameworks - Platform services · Timers, CPU/tick access, system info, versioning, and performance hooks.
frameworks - Path primitives · Arc, curve, path shortening, and other geometric primitive builders.
frameworks/diagram/vertexprimitive - Vertex generation · Converts higher-level geometry into renderable vertex streams.
frameworks/diagram/vertexgenerate - Curve depiction · Generates smooth curve points and depiction helpers for vector paths.
frameworks/diagram/depiction - Rasterizer · Antialiasing, scanline rasterization, and clipping for 2D rendering.
frameworks/diagram/rasterizer - Paint logic · Shared paint behavior used by the diagram rendering pipeline.
frameworks/diagram/common - HALS bridge · Platform and driver-facing adaptation layer for graphics engine and framebuffer access.
frameworks/hals - CPU / tick · CPU capability and tick primitives used by portable graphics code.
frameworks
Tests
Unit tests for core value and math layers.
- Unit tests · Tests covering color, geometry, math, timer, list, rect, style, transform, and vector behavior.
test
Other components
- UI / surface / WMS · Higher-level graphics modules that consume this library's shared types and rendering helpers.
Connections 23
- UI / surface / WMS → Public gfx utils: uses · Top-level graphics consumers depend on the stable public utility API.
- UI / surface / WMS → Diagram API: uses · Rendering clients consume the public diagram and rasterization interfaces.
- Public gfx utils → Core types: declares · Public headers expose shared data contracts implemented in frameworks/.
- Public gfx utils → Geometry math: declares · Public API publishes geometry, transform, and math helpers.
- Public gfx utils → Containers / memory: declares · Public API includes container and memory abstractions.
- Public gfx utils → Platform services: declares · Public API exposes timer, system, and performance interfaces.
- Diagram API → Path primitives: exposes · Public diagram interfaces wrap vector geometry primitives.
- Diagram API → Vertex generation: exposes · Public headers define stroke and dash generation contracts.
- Diagram API → Rasterizer: exposes · Public headers define scanline and rasterizer abstractions.
- Diagram API → Paint logic: exposes · Public interfaces include fill and paint helpers.
- Inner HAL API → HALS bridge: contracts for · Inner contracts define the boundary to HALS implementations.
- Inner HAL API → CPU / tick: contracts for · Internal interfaces provide CPU and tick abstractions.
- Core types → Public gfx utils: implements · Framework sources implement the shared public types.
- Geometry math → Public gfx utils: implements · Framework sources implement geometry and transform utilities.
- Path primitives → Vertex generation: feeds · Primitive geometry is expanded into renderable vertex streams.
- Vertex generation → Rasterizer: feeds · Generated vertices are consumed by rasterization stages.
- Curve depiction → Vertex generation: prepares · Curve depiction shapes geometry before vertex expansion.
- Rasterizer → Paint logic: uses · Rasterization relies on shared paint and fill logic.
- Platform services → HALS bridge: supports · Runtime platform services back the hardware adaptation layer.
- CPU / tick → HALS bridge: supports · CPU and tick primitives underpin HALS implementations.
- Unit tests → Core types: verifies · Unit tests cover the foundational value types and helpers.
- Unit tests → Geometry math: verifies · Unit tests exercise geometry and transform behavior.
- Unit tests → Platform services: verifies · Unit tests exercise timer and platform utility behavior.