Egloo 项目结构分析

项目结构

目录结构

csharp 复制代码

Egloo/
├── library/                 # 核心库模块
│   ├── src/
│   │   ├── commonMain/     # 跨平台通用代码
│   │   ├── androidJvmMain/ # Android JVM 特定代码
│   │   ├── androidNativeMain/      # Android Native 通用代码
│   │   ├── androidNative32BitMain/ # Android 32位特定代码
│   │   └── androidNative64BitMain/ # Android 64位特定代码
│   ├── build.gradle.kts    # 库模块构建脚本
│   └── proguard-rules.pro  # ProGuard 混淆规则
│
├── demo/                    # 示例应用模块
│   ├── src/
│   │   └── main/
│   │       ├── java/      # 示例代码
│   │       └── res/       # 资源文件
│   ├── build.gradle.kts    # 示例应用构建脚本
│   └── proguard-rules.pro  # ProGuard 混淆规则
│
├── docs/                    # 文档目录
│   ├── _about/             # 关于文档
│   ├── _docs/              # API文档
│   ├── _extra/             # 额外信息
│   ├── css/                # 样式文件
│   ├── icons/              # 图标资源
│   ├── static/             # 静态资源
│   └── _config.yml         # Jekyll 配置
│
├── gradle/                  # Gradle 包装器
│   └── wrapper/
│
└── build.gradle.kts        # 项目级构建脚本

模块说明

1. Library 模块 (library/)

核心库模块包含了 Egloo 框架的所有核心功能实现，采用 Kotlin Multiplatform 架构设计。

1.1 多平台支持

bash 复制代码

library/
└── src/
    ├── commonMain/           # 跨平台通用代码
    ├── androidJvmMain/      # Android JVM 实现
    ├── androidNativeMain/   # Android Native 通用实现
    ├── androidNative32BitMain/  # 32位 Native 实现
    └── androidNative64BitMain/  # 64位 Native 实现

1.2 核心功能模块 (com.otaliastudios.opengl)

ini 复制代码

com.otaliastudios.opengl/
├── buffer/              # 缓冲区管理
│   ├── GlBuffer.kt             # 通用缓冲区
│   └── GlShaderStorageBuffer.kt # 着色器存储缓冲区
│
├── core/               # 核心功能
│   ├── EglCore.kt             # EGL上下文管理
│   ├── EglNativeCore.kt       # Native EGL实现
│   ├── Egloo.kt              # 框架入口
│   ├── GlBindable.kt         # 绑定接口
│   └── GlViewportAware.kt    # 视口管理
│
├── draw/               # 绘制组件
│   ├── Gl2dDrawable.kt       # 2D绘制基类
│   ├── Gl3dDrawable.kt       # 3D绘制基类
│   ├── GlCircle.kt          # 圆形
│   ├── GlRect.kt            # 矩形
│   ├── GlRoundRect.kt       # 圆角矩形
│   ├── GlSquare.kt          # 正方形
│   ├── GlTriangle.kt        # 三角形
│   └── GlPolygon.kt         # 多边形
│
├── geometry/           # 几何图形
│   ├── PointF.kt            # 点
│   ├── RectF.kt            # 矩形区域
│   ├── IndexedPointF.kt     # 索引点
│   └── IndexedSegmentF.kt   # 索引线段
│
├── program/            # 着色器程序
│   └── GlFlatProgram.kt     # 基础着色器程序
│
├── scene/             # 场景管理
│   └── [场景相关类]
│
├── surface/           # 渲染表面
│   ├── EglSurface.kt        # 基础表面
│   └── EglWindowSurface.kt  # 窗口表面
│
├── texture/           # 纹理处理
│   └── [纹理相关类]
│
├── extensions/        # 扩展工具
│   ├── Buffers.kt           # 缓冲区工具
│   └── Matrix.kt            # 矩阵操作
│
└── types/             # 类型定义
    └── buffers.kt           # 缓冲区类型

1.3 平台特定实现

Android JVM (androidJvmMain)

csharp 复制代码

androidJvmMain/
└── com.otaliastudios.opengl/
    ├── core/
    │   ├── EglConfigChooser.kt    # EGL配置选择器
    │   ├── EglContextFactory.kt   # EGL上下文工厂
    │   └── EglCore.kt            # Android EGL实现
    ├── surface/
    │   └── EglWindowSurface.kt   # Android窗口表面
    └── internal/                 # 内部实现

Android Native (androidNativeMain)

csharp 复制代码

androidNativeMain/
└── com.otaliastudios.opengl/
    ├── core/
    │   └── EglCore.kt           # Native EGL实现
    ├── surface/
    │   └── EglWindowSurface.kt  # Native窗口表面
    └── internal/                # Native内部实现

1.4 主要特性

模块	功能	关键类
Core	EGL/GL上下文管理	EglCore, Egloo
Draw	2D/3D图形绘制	GlDrawable, GlCircle, GlRect
Program	着色器程序	GlFlatProgram
Surface	渲染表面管理	EglSurface, EglWindowSurface
Texture	纹理处理	GlTexture
Buffer	缓冲区管理	GlBuffer
Scene	场景管理	Scene
Geometry	几何图形	PointF, RectF

2. Demo 模块 (demo/)

示例应用模块展示了 Egloo 框架的各种用法和功能。包含两个主要示例：

ShapesActivity: 展示基本图形绘制功能
- 使用 GlFlatProgram 绘制彩色形状
- 包含圆形、三角形和圆角矩形的动画示例
- 演示了 GlScene 的使用方法
- 展示了如何使用 EglCore 和 EglWindowSurface 进行渲染
VideoActivity: 展示视频纹理处理功能
- 使用 GlTextureProgram 处理视频纹理
- 集成 ExoPlayer 进行视频播放
- 展示了如何将视频内容渲染到不同形状（矩形、圆角矩形、自定义网格）
- 演示了如何处理视频宽高比和屏幕适配

bash 复制代码

demo/
└── src/
    └── main/
        ├── java/
        │   └── com/otaliastudios/opengl/demo/
        │       ├── ShapesActivity.kt      # 形状示例活动
        │       │                          # - 使用EglCore和EglWindowSurface
        │       │                          # - 绘制动画形状（圆形、三角形、圆角矩形）
        │       │                          # - 使用GlFlatProgram着色器程序
        │       │
        │       └── VideoActivity.kt       # 视频示例活动
        │                                  # - 使用GLSurfaceView
        │                                  # - 集成ExoPlayer播放视频
        │                                  # - 使用GlTextureProgram处理视频纹理
        │                                  # - 支持多种形状的视频渲染
        │
        ├── AndroidManifest.xml           # 应用清单文件
        ├── logo-web.png                  # 应用图标
        │
        └── res/
            ├── layout/                   # 布局文件
            │   ├── activity_shapes.xml   # 形状示例布局
            │   └── activity_video.xml    # 视频示例布局
            │
            ├── menu/                     # 菜单资源
            │   ├── activity_shapes.xml   # 形状示例菜单
            │   └── activity_video.xml    # 视频示例菜单
            │
            ├── drawable/                 # 图片资源
            │   └── ic_launcher_background.xml
            │
            ├── drawable-v24/            # 矢量图资源
            │   └── ic_launcher_foreground.xml
            │
            ├── mipmap-*/                # 各种分辨率的图标资源
            │   ├── logo.png
            │   ├── logo_background.png
            │   └── logo_foreground.png
            │
            └── values/                  # 配置文件
                ├── colors.xml           # 颜色定义（包含形状颜色）
                ├── strings.xml          # 字符串资源
                └── styles.xml           # 样式定义

示例功能概述

示例	主要功能	核心类	特点
ShapesActivity	基本图形绘制	EglCore, GlFlatProgram, GlScene	动画效果、颜色变换、形状变换
VideoActivity	视频纹理处理	GLSurfaceView, GlTextureProgram, SurfaceTexture	ExoPlayer集成、多形状渲染、宽高比处理

3. 文档结构 (docs/)

文档使用 Jekyll 静态站点生成器，采用模块化组织。

csharp 复制代码

docs/
├── _about/                  # 关于页面
│   ├── changelog.md        # 更新日志
│   ├── getting-started.md  # 入门指南
│   └── install.md         # 安装说明
│
├── _docs/                  # API文档
│   ├── drawables.md       # 绘制对象
│   ├── egl-management.md  # EGL管理
│   ├── programs.md        # 着色器程序
│   ├── scenes.md         # 场景管理
│   └── textures.md       # 纹理处理
│
├── _extra/                 # 额外信息
│   ├── contact.md        # 联系方式
│   ├── contributing.md    # 贡献指南
│   └── donate.md         # 赞助信息
│
└── static/                 # 静态资源
    ├── banner.png         # 横幅图片
    └── screenshots/       # 截图

构建系统

1. 项目级配置

build.gradle.kts:

kotlin 复制代码

buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
        classpath("com.android.tools.build:gradle:$gradleVersion")
    }
}

2. 库模块配置

library/build.gradle.kts:

kotlin 复制代码

plugins {
    id("com.android.library")
    kotlin("multiplatform")
}

kotlin {
    android()
    androidNativeArm32()
    androidNativeArm64()
    
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$coroutinesVersion")
            }
        }
        
        val androidMain by getting {
            dependencies {
                implementation("androidx.annotation:annotation:$androidxVersion")
            }
        }
    }
}

3. 示例模块配置

demo/build.gradle.kts:

kotlin 复制代码

plugins {
    id("com.android.application")
    kotlin("android")
}

android {
    compileSdk = 33
    defaultConfig {
        applicationId = "com.egloo.demo"
        minSdk = 21
        targetSdk = 33
    }
}

dependencies {
    implementation(project(":library"))
    implementation("androidx.appcompat:appcompat:$appcompatVersion")
}

资源组织

1. 着色器实现

着色器代码直接嵌入在程序类中作为常量字符串，而不是存储在外部资源文件中：

kotlin 复制代码

// 在 GlTextureProgram.kt 中
private const val SIMPLE_VERTEX_SHADER = """
    attribute vec4 aPosition;
    attribute vec4 aTextureCoord;
    uniform mat4 uMVPMatrix;
    uniform mat4 uTexMatrix;
    varying vec2 vTextureCoord;
    void main() {
        gl_Position = uMVPMatrix * aPosition;
        vTextureCoord = (uTexMatrix * aTextureCoord).xy;
    }
"""

private const val SIMPLE_FRAGMENT_SHADER = """
    precision mediump float;
    varying vec2 vTextureCoord;
    uniform samplerExternalOES sTexture;
    void main() {
        gl_FragColor = texture2D(sTexture, vTextureCoord);
    }
"""

// 在 GlFlatProgram.kt 中
private const val VERTEX_SHADER = """
    attribute vec4 aPosition;
    uniform mat4 uMVPMatrix;
    void main() {
        gl_Position = uMVPMatrix * aPosition;
    }
"""

private const val FRAGMENT_SHADER = """
    precision mediump float;
    uniform vec4 uColor;
    void main() {
        gl_FragColor = uColor;
    }
"""

2. 示例资源

css 复制代码

demo/src/main/res/
├── drawable/
│   ├── texture_sample.png
│   └── normal_map.png
├── raw/
│   ├── model.obj
│   └── custom_shader.glsl
└── values/
    ├── colors.xml
    └── strings.xml

版本控制

1. Git 忽略文件

.gitignore:

bash 复制代码

# Gradle
.gradle/
build/

# IDE
.idea/
*.iml
local.properties

# Generated
bin/
gen/
out/

# Logs
*.log

# OS specific
.DS_Store
Thumbs.db

2. 分支策略

main: 稳定版本分支
develop: 开发分支
feature/*: 功能分支
release/*: 发布分支
hotfix/*: 紧急修复分支

持续集成

1. GitHub Actions

yaml 复制代码

name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up JDK
        uses: actions/setup-java@v2
        with:
          java-version: '11'
      - name: Build
        run: ./gradlew build
      - name: Test
        run: ./gradlew test

发布配置

1. Maven 发布

library/build.gradle.kts:

kotlin 复制代码

publishing {
    publications {
        create<MavenPublication>("maven") {
            groupId = "com.egloo"
            artifactId = "egloo"
            version = "1.0.0"
            
            from(components["kotlin"])
        }
    }
}

2. 文档发布

docs/_config.yml:

yaml 复制代码

title: Egloo Documentation
baseurl: "/egloo"
url: "https://egloo.github.io"
theme: jekyll-theme-minimal