# openharmony/graphic_graphic_utils_lite architecture

> Architecture diagram of the GitHub repository openharmony/graphic_graphic_utils_lite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openharmony/graphic_graphic_utils_lite
- Repository: https://github.com/openharmony/graphic_graphic_utils_lite

## Overview

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: [`interfaces/kits/gfx_utils`](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/interfaces/kits/gfx_utils) (Public gfx utils), [`interfaces/kits/gfx_utils/diagram`](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/interfaces/kits/gfx_utils/diagram) (Diagram API), [`frameworks/diagram/vertexgenerate`](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/frameworks/diagram/vertexgenerate) (Vertex generation), [`test`](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/test) (Unit tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "API surface"
  node_kits_core["Public gfx utils<br/>kits API"]
  node_kits_diagram["Diagram API<br/>kits API"]
  node_innerkits["Inner HAL API<br/>internal contracts"]
end

subgraph "Implementations"
  node_core_types["Core types<br/>shared value types"]
  node_geometry["Geometry math<br/>math helpers"]
  node_containers["Containers / memory<br/>support layer"]
  node_platform_info["Platform services<br/>runtime info"]
  node_diagram_primitives["Path primitives<br/>vector geometry"]
  node_vertexgen["Vertex generation<br/>stroke/dash expansion"]
  node_depiction["Curve depiction<br/>curve smoothing"]
  node_rasterizer["Rasterizer<br/>scanline engine"]
  node_paint["Paint logic<br/>fill/compositing"]
  node_hals["HALS bridge<br/>hardware adaptation"]
  node_cpu_tick["CPU / tick<br/>low-level runtime"]
end

subgraph "Tests"
  node_tests["Unit tests<br/>validation"]
end

node_consumers["UI / surface / WMS<br/>downstream consumers"]

node_consumers -->|"uses"| node_kits_core
node_consumers -->|"uses"| node_kits_diagram
node_kits_core -->|"declares"| node_core_types
node_kits_core -->|"declares"| node_geometry
node_kits_core -->|"declares"| node_containers
node_kits_core -->|"declares"| node_platform_info
node_kits_diagram -->|"exposes"| node_diagram_primitives
node_kits_diagram -->|"exposes"| node_vertexgen
node_kits_diagram -->|"exposes"| node_rasterizer
node_kits_diagram -->|"exposes"| node_paint
node_innerkits -->|"contracts for"| node_hals
node_innerkits -->|"contracts for"| node_cpu_tick
node_core_types -->|"implements"| node_kits_core
node_geometry -->|"implements"| node_kits_core
node_diagram_primitives -->|"feeds"| node_vertexgen
node_vertexgen -->|"feeds"| node_rasterizer
node_depiction -->|"prepares"| node_vertexgen
node_rasterizer -->|"uses"| node_paint
node_platform_info -->|"supports"| node_hals
node_cpu_tick -->|"supports"| node_hals
node_tests -->|"verifies"| node_core_types
node_tests -->|"verifies"| node_geometry
node_tests -->|"verifies"| node_platform_info

click node_kits_core "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/interfaces/kits/gfx_utils"
click node_kits_diagram "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/interfaces/kits/gfx_utils/diagram"
click node_innerkits "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/interfaces/innerkits"
click node_core_types "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/frameworks"
click node_geometry "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/frameworks"
click node_containers "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/frameworks"
click node_platform_info "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/frameworks"
click node_diagram_primitives "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/frameworks/diagram/vertexprimitive"
click node_vertexgen "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/frameworks/diagram/vertexgenerate"
click node_depiction "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/frameworks/diagram/depiction"
click node_rasterizer "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/frameworks/diagram/rasterizer"
click node_paint "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/frameworks/diagram/common"
click node_hals "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/frameworks/hals"
click node_cpu_tick "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/frameworks"
click node_tests "https://github.com/openharmony/graphic_graphic_utils_lite/tree/master/test"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_kits_core,node_kits_diagram,node_innerkits toneBlue
class node_core_types,node_geometry,node_containers,node_platform_info,node_diagram_primitives,node_vertexgen,node_depiction,node_rasterizer,node_paint,node_hals,node_cpu_tick toneAmber
class node_tests toneMint
class node_consumers toneNeutral
```

## Components

### API surface

Public kits APIs and internal contracts exposed to other graphics modules.

- [Public gfx utils](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/interfaces/kits/gfx_utils): kits API · Stable public graphics utility headers for shared types, math, containers, and diagnostics. · `interfaces/kits/gfx_utils`
- [Diagram API](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/interfaces/kits/gfx_utils/diagram): kits API · Public 2D drawing, path, scanline, fill, and image-filter interfaces. · `interfaces/kits/gfx_utils/diagram`
- [Inner HAL API](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/interfaces/innerkits): internal contracts · Internal interfaces for timers, CPU helpers, threading primitives, and HALS adapters. · `interfaces/innerkits`

### Implementations

Concrete utility, rendering, and HALS code under frameworks/.

- [Core types](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/frameworks): shared value types · Color, rect, style, image, buffer, and other common data contracts. · `frameworks`
- [Geometry math](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/frameworks): math helpers · 2D geometry, affine transforms, coordinate math, and general transform utilities. · `frameworks`
- [Containers / memory](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/frameworks): support layer · Container and memory abstraction utilities used by graphics code. · `frameworks`
- [Platform services](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/frameworks): runtime info · Timers, CPU/tick access, system info, versioning, and performance hooks. · `frameworks`
- [Path primitives](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/frameworks/diagram/vertexprimitive): vector geometry · Arc, curve, path shortening, and other geometric primitive builders. · `frameworks/diagram/vertexprimitive`
- [Vertex generation](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/frameworks/diagram/vertexgenerate): stroke/dash expansion · Converts higher-level geometry into renderable vertex streams. · `frameworks/diagram/vertexgenerate`
- [Curve depiction](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/frameworks/diagram/depiction): curve smoothing · Generates smooth curve points and depiction helpers for vector paths. · `frameworks/diagram/depiction`
- [Rasterizer](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/frameworks/diagram/rasterizer): scanline engine · Antialiasing, scanline rasterization, and clipping for 2D rendering. · `frameworks/diagram/rasterizer`
- [Paint logic](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/frameworks/diagram/common): fill/compositing · Shared paint behavior used by the diagram rendering pipeline. · `frameworks/diagram/common`
- [HALS bridge](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/frameworks/hals): hardware adaptation · Platform and driver-facing adaptation layer for graphics engine and framebuffer access. · `frameworks/hals`
- [CPU / tick](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/frameworks): low-level runtime · CPU capability and tick primitives used by portable graphics code. · `frameworks`

### Tests

Unit tests for core value and math layers.

- [Unit tests](https://github.com/openharmony/graphic_graphic_utils_lite/tree/HEAD/test): validation · Tests covering color, geometry, math, timer, list, rect, style, transform, and vector behavior. · `test`

### Other components

- **UI / surface / WMS**: downstream consumers · Higher-level graphics modules that consume this library's shared types and rendering helpers.

## Connections

- 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.
