flutter_globe_3d 1.2.1

High-performance Flutter widget that renders an interactive 3D Earth globe using GPU fragment shaders; supports markers, connections and smooth gestures.

Flutter Globe 3D — English / 中文

GPU-accelerated 3D globe widget for Flutter. 使用 Fragment Shader 在 GPU 上直接渲染球体纹理，性能强大，适合需要高帧率渲染的场景。

---

Demo GIFs & Screenshots

• Live recording (spin):

  

• Connection spark demo:

  

• Screenshot — Earth:

  

• Screenshot — Spark overlay:

  

---

Language / 语言

This README contains both English and Chinese sections. Read the section you prefer.

本说明同时提供英文与中文内容，向下查找对应语言段落即可。

---

English

Quick summary

Flutter Globe 3D is a performant 3D globe widget implemented with Flutter Fragment Shaders. Rendering runs on the GPU (fragment shader), the Dart UI thread is not used for sphere shading; raster thread workload is small — the result is smooth animation and the ability to reach very high frame rates (e.g. 60–120 FPS on capable devices).

Key advantages:

• GPU shader-based mapping -> high performance
• Low Dart-side cost (no heavy UI work per-frame)
• Smooth anti-aliased rendering and accurate texture mapping

Compatibility:

• As of version 1.1.4 the display/layout defects have been fixed — the widget now adapts to arbitrary dynamic layouts (ListView, Column, Row, Stack, etc.). If you find any remaining issues, please open an issue or submit a PR.

Installation

Add to pubspec.yaml:

dependencies:
  flutter_globe_3d: ^1.1.4

Add assets (example):

flutter:
  assets:
    - assets/shaders/globe.frag
    - assets/earth_texture.png
    - example/images/record_earth.gif
    - example/images/record_spark.gif

Usage (updated example)

This example matches the example/main.dart shipped with the package and demonstrates texture loading, markers and connections:

import 'package:flutter/material.dart';
import 'package:flutter_globe_3d/flutter_globe_3d.dart';

class ExampleApp extends StatefulWidget {
  @override
  State<ExampleApp> createState() => _ExampleAppState();
}

class _ExampleAppState extends State<ExampleApp> {
  final EarthController controller = EarthController();

  @override
  void dispose() {
    controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('3D Globe')),
      body: Center(
        child: Flutter3DGlobe(
          controller: controller,
          texture: AssetImage('assets/example.png'),
          radius: 200,
          markers: [
            EarthMarker(
              id: 'ny',
              latitude: 40.7128,
              longitude: -74.0060,
              child: Container(width: 12, height: 12, decoration: BoxDecoration(color: Colors.red, shape: BoxShape.circle)),
              label: 'New York',
            ),
          ],
          connections: [],
        ),
      ),
    );
  }
}

Configuration options & controller tips

This section shows how to use the EarthConfig flags and the EarthController.autoRotate programmatic toggle.

• polarLock: when true, vertical rotation (pitch) is disabled and the globe only rotates horizontally.
• zoomLock: when true, zoom changes from gestures or code are ignored.

Example (English):

final controller = EarthController(
  config: const EarthConfig(polarLock: true, zoomLock: false),
  autoRotate: true,
);

// Temporarily pause auto-rotate (for example during a custom animation)
controller.autoRotate = false;

// Resume auto-rotate
controller.autoRotate = true;

示例（中文）：

// 创建控制器并锁定极轴（禁止上下倾斜），允许缩放
final controller = EarthController(
  config: const EarthConfig(polarLock: true, zoomLock: false),
);

// 在自定义交互期间暂停自动旋转
controller.autoRotate = false;

// 交互结束后恢复自动旋转
controller.autoRotate = true;

Notes:

• The widget defers to EarthController.autoRotate as the single source of truth for automatic rotation. If you previously used a local widget flag for auto-rotation, migrate that logic to the controller.
• polarLock and zoomLock are immutable configuration values on EarthConfig. Create the controller with the desired EarthConfig to enable the locks.

Technical notes

• Implementation: the globe surface is shaded using a fragment shader (assets/shaders/globe.frag). The shader computes spherical mapping and lighting on the GPU.
• Performance: because the heavy work happens in the shader, the Dart UI thread remains mostly idle; only a small amount of state (rotation/zoom) is sent per frame. This design minimizes CPU overhead and lets modern devices reach very high frame rates.
• Raster thread: shaders run in the GPU/raster pipeline — the plugin keeps raster thread usage small.

When things go wrong

• If you see the error does not contain any shader data, make sure the shader asset is declared in your app's pubspec.yaml under flutter.assets and shaders (if using Flutter's shader tooling).
• Example shaderAssetPath default is assets/shaders/globe.frag. Do not prefix with packages/ when the asset is included in the same package.

---

中文（简体）

简要说明

本插件使用 Flutter 的 Fragment Shader 在 GPU 上直接绘制球体纹理映射。渲染在 GPU 侧完成，不占用 Dart UI 线程，只有很少的 raster 线程开销，因此在支持的设备上可以非常流畅（可达 60–120FPS）。推荐用于需要高帧率的球体演示场景。

优点：

• 基于着色器的映射，性能强大
• 几乎不占用 Dart UI 线程
• 抗锯齿、贴图映射准确

安装与资源

在 pubspec.yaml 中添加依赖与资源：

dependencies:
  flutter_globe_3d: ^1.1.4

flutter:
  assets:
    - assets/shaders/globe.frag
    - assets/example.png
    - example/images/record_earth.gif
    - example/images/record_spark.gif

注意：Shader 文件须在 assets 下声明并与 shaderAssetPath 对应。

使用示例

请参考 example/main.dart：示例演示了如何创建 EarthController，加载纹理，添加标记，并将 Flutter3DGlobe 嵌入页面。

（示例代码见上方 English 部分，已更新以匹配示例工程。）

技术实现说明

兼容性：

• 自 v1.1.4 起已修复显示/布局问题；组件现在可以适配任意动态布局（如 ListView、Column、Row、Stack 等）。如仍发现问题欢迎提交 issue 或 PR。

Contributing / 贡献

欢迎提出 issue 或 PR。如果你能帮助改善布局兼容性（例如在更多容器与约束下也能稳定渲染），非常感谢！

License

MIT — 详见 LICENSE

---

Contact / 支持

• Issues: https://github.com/XiaoNaoWeiSuo/flutter_globe_3d/issues