# sokol

vlib/sokol模块已经对soko图形库进行封装，可以使用。

## sokol图形库参考

sokol是ui依赖的C图形库，想要更清楚理解ui是如何运作，得掌握一下所依赖的sokol图形库：

官方网址：<https://github.com/floooh/sokol>

官方DEMO：<https://floooh.github.io/sokol-html5/index.html> (WASM版本)

官方DEMO源代码：<https://github.com/floooh/sokol-samples>

作者整体思路文档：https：//floooh.github.io/2017/07/29/sokol-gfx-tour.html

官方简介：简单，单文件，跨平台库，可供C/C++使用，C写的。

整个库包含这几个C文件，每个C文件可以单独使用：

Cross-platform libraries：

* **sokol\_gfx.h**： 3D-API wrapper (GL + Metal + D3D11)
* **sokol\_app.h**： app framework wrapper (entry + window + 3D-context + input)
* **sokol\_time.h**： time measurement
* **sokol\_audio.h**： minimal buffer-streaming audio playback
* **sokol\_fetch.h**： asynchronous data streaming from HTTP and local filesystem
* **sokol\_args.h**： unified cmdline/URL arg parser for web and native apps

Utility libraries：

* **sokol\_imgui.h**： sokol\_gfx.h rendering backend for [Dear ImGui](https://github.com/lydiandy/vlang_note/blob/master/content/https%EF%BC%9A/github.com/ocornut/imgui/README.md)
* **sokol\_gl.h**： OpenGL 1.x style immediate-mode rendering API on top of sokol\_gfx.h
* **sokol\_fontstash.h**： sokol\_gl.h rendering backend for [fontstash](https://github.com/memononen/fontstash)
* **sokol\_gfx\_imgui.h**： debug-inspection UI for sokol\_gfx.h (implemented with Dear ImGui)

vui目前使用了这4个，主要是前两个核心文件，已包含在V源代码的thirdparth/sokol中，无需单独下载。

**sokol\_gfx.h**

* 简单，现代地封装了GLES2/WebGL， GLES3/WebGL2， GL3.3， D3D11 和 Metal。
* 提供buffers， images， shaders， pipeline-state-objects 和 render-passes。
* 无需控制窗体的创建或者3D API的上下文初始化。
* 无需提供着色器方言交叉翻译。

**sokol\_app.h**

* 统一的应用入口。
* 单窗体或画布提供3D渲染。
* 3D上下文初始化。
* 事件驱动的键盘，鼠标，触摸板输入。
* 支持的平台： Win32， MacOS， Linux (X11)， iOS， WASM/asm.js， Android (planned： RaspberryPi)。
* 支持的3D-APIs： GL3.3 (GLX/WGL)， Metal， D3D11， GLES2/WebGL， GLES3/WebGL2。

**sokol\_gl.h**

OpenGL 1.x样式的立即模式渲染API，基于sokol\_gfx.h。

**sokol\_fontstash.h**

为[fontstash](https://github.com/memononen/fontstash)提供渲染后端。

## sapp模块

* 枚举

  EventType //事件类型

  MouseButton //鼠标按键

  KeyCode //键盘按键
* 结构体

  sapp\_desc //应用程序选项

  sapp\_event //窗体事件:鼠标，键盘，触摸板等窗口事件

  sapp\_touchpoint //触摸板事件类型
* 回调函数

  init\_cb //完成初始化后回调

  frame\_cb //刷新每一帧之前回调，通常是1秒钟，回调60次

  event\_cb //捕捉事件后回调

  cleanup\_cb //退出前回调

  fail\_cb //报错后回调
* 带用户自定义数据的回调函数

  init\_userdata\_cb

  frame\_userdata\_cb

  event\_userdata\_cb

  cleanup\_userdata\_cb

  fail\_userdata\_cb

  简单例子：

  ```v
  module main

  import sokol
  import sokol.sapp

  fn main() {
  	//创建app
  	app ：= sapp.Desc{
  		window_title: 'myapp'.str
  		width: 640
  		height: 480
  		high_dpi: true
  		init_cb: init_cb // app完成初始化后回调
  		frame_cb: frame_cb // app刷新每一帧之前回调，通常是1秒钟，回调60次
  		cleanup_cb: cleanup_cb // app退出前回调
  		fail_cb: fail_cb // app报错后回调
  		event_cb: event_cb // app捕捉事件后回调
  		html5_canvas_name: 'canvas'.str
  	}
  	//启动
  	sapp.run(&app)
  }

  fn init_cb() {
  	v := sapp.isvalid()
  	println(v)
  	sapp.show_mouse(true)
  }

  fn frame_cb() {
  }

  fn cleanup_cb() {
  }

  fn fail_cb(msg &u8) {
  }

  fn event_cb(e voidptr) {
  	event := &sapp.Event(e)
  	match event.@type {
  		.key_up {
  			println(u8(event.key_code).str())
  			if event.key_code == sapp.KeyCode.q {
  				sapp.quit()
  			}
  		}
  		.mouse_move {
  			println('x:$event.mouse_x,y:$event.mouse_y')
  			println('framecount:$event.frame_count')
  		}
  		.resized {
  			println('resized:width:$event.window_width,height:$event.window_height')
  		}
  		else {}
  	}
  }
  ```

***

## sgx模块

* 枚举

  Backend //后端类型

  PixelFormat //像素点格式

  ResourceState

  Usage

  BufferType

  ImageType

  CubeFace

  ShaderStage

  PrimitiveType

  Filter

  Wrap

  BorderColor

  VertexFormat //顶点数据格式

  VertexStep

  UniformType

  CullMode

  FaceWinding

  CompareFunc

  StencilOp

  BlendFactor

  BlendOp

  ColorMask

  Action
* 结构体

  sg\_desc //gfx选项

  sg\_context //上下文

  sg\_buffer\_desc //缓存数据选项

  sg\_image\_desc //图片数据选项

  sg\_shader\_desc //着色器选项

  sg\_pipeline\_desc //渲染管线选项

  sg\_pass\_desc //渲染通道选项

  sg\_attachment\_desc //颜色附加点选项

  sg\_buffer //缓存数据

  sg\_image //图像数据

  sg\_shader //着色器

  sg\_pipeline //渲染管线

  sg\_pass //渲染通路，一次绘制

  sg\_slot\_info

  sg\_buffer\_info

  sg\_image\_info

  sg\_shader\_info

  sg\_pipeline\_info

  sg\_pass\_info
* 函数

  初始化gfx：

  setup() //根据选项，初始化gfx

  关闭sg：

  shutdown() //关闭gfx

  创建资源对象：

  make\_buffer()

  make\_image()

  make\_shader()

  make\_pipeline()

  make\_pass()

  开始渲染：

  begin\_default\_pass() //开始默认的渲染通道

  begin\_pass() 开始自定义渲染通道

  设置：

  apply\_viewport() //设置视口

  apply\_scissor\_rect() //设置裁剪矩形

  apply\_pipeline() //设置渲染管线

  apply\_bindings() //设置资源绑定

  apply\_uniforms() //设置统一变量

  绘制：

  draw()

  完成/提交：

  end\_pass() //结束渲染通道

  commit() //提交

  更新资源对象：

  update\_buffer() //更新缓存数据

  update\_image() //更新图像数据

  append\_buffer() //追加缓存数据

  查询内部资源属性：

  query\_buffer\_info()

  query\_image\_info()

  query\_shader\_info()

  query\_pipeline\_info()

  query\_pass\_info()

  查询后端：

  query\_backend()

  销毁资源对象：

  destroy\_buffer()

  destroy\_image()

  destroy\_shader()

  destroy\_pipeline()

  destroy\_pass()

  上下文：

  setup\_context()

  activate\_context()

  discard\_context()

## sgl模块

* 枚举

  SglError
* 结构体

  sgl\_pipeline

  sgl\_desc\_t
* 函数

  初始化：

  setup()

  关闭：

  shutdown()

  创建/销毁：

  make\_pipeline()

  destroy\_pipeline()

  渲染状态函数：

  viewport()

  scissor\_rect()

  enable\_texture()

  disable\_texture()

  texture()

  渲染命令：

  begin\_points()

  begin\_lines()

  begin\_line\_strip()

  begin\_triangles()

  begin\_triangle\_strip()

  begin\_quads()

  ...

  绘制：

  draw()

  结束：

  end()

## sfons模块

​ fontstash的字体渲染器

​ create() //创建字体上下文

​ destroy() //销毁字体上下文

​ rgba() //转换颜色格式从RGBA到uint32\_t，fontstash需要的

​ flush()


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://lydiandylin.gitbook.io/vlang/sokol.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.