基于 WebGL Specifications 最全面的API释疑。
类型以及对象定义
这部分内容主要定义一部分类型和数据结构。
typedef unsigned long GLenum;
typedef boolean GLboolean;
typedef unsigned long GLbitfield;
typedef byte GLbyte;
typedef short GLshort;
typedef long GLint;
typedef long GLsizei;
typedef long long GLintptr;
typedef long long GLsizeiptr;
// 这个类型应该是 无符号整型 8位
// 但是Web IDL中并不存在这种类型
// 所以用 octet 代替 占位
typedef octet GLubyte;
typedef unsigned short GLushort;
typedef unsigned long GLuint;
typedef unrestricted float GLfloat;
typedef unrestricted float GLclampf;
// 由 WebGLContextAttributes 引用
enum WebGLPowerPreference {
"default", "low-power", "high-performance" };
// 获取上下文时支持的参数
// getContext('webgl', <WebGLContextAttributes>)
dictionary WebGLContextAttributes {
boolean alpha = true;
boolean depth = true;
boolean stencil = false;
boolean antialias = true;
boolean premultipliedAlpha = true;
boolean preserveDrawingBuffer = false;
WebGLPowerPreference powerPreference = "default";
boolean failIfMajorPerformanceCaveat = false;
};
// [Exposed=(Window,Worker)] 代表可以同时在主线程和后台线程使用本对象
[Exposed=(Window,Worker)]
interface WebGLObject {
};
[Exposed=(Window,Worker)]
interface WebGLBuffer : WebGLObject {
};
[Exposed=(Window,Worker)]
interface WebGLFramebuffer : WebGLObject {
};
[Exposed=(Window,Worker)]
interface WebGLProgram : WebGLObject {
};
[Exposed=(Window,Worker)]
interface WebGLRenderbuffer : WebGLObject {
};
[Exposed=(Window,Worker)]
interface WebGLShader : WebGLObject {
};
[Exposed=(Window,Worker)]
interface WebGLTexture : WebGLObject {
};
[Exposed=(Window,Worker)]
interface WebGLUniformLocation {
};
[Exposed=(Window,Worker)]
interface WebGLActiveInfo {
readonly attribute GLint size;
readonly attribute GLenum type;
readonly attribute DOMString name;
};
[Exposed=(Window,Worker)]
interface WebGLShaderPrecisionFormat {
readonly attribute GLint rangeMin;
readonly attribute GLint rangeMax;
readonly attribute GLint precision;
};
typedef (ImageBitmap or
ImageData or
HTMLImageElement or
HTMLCanvasElement or
HTMLVideoElement or
OffscreenCanvas) TexImageSource;
typedef ([AllowShared] Float32Array or sequence<GLfloat>) Float32List;
typedef ([AllowShared] Int32Array or sequence<GLint>) Int32List;
interface mixin WebGLRenderingContextBase {
// 内容整理到 'WebGLRenderingContext 对象'
}
interface mixin WebGLRenderingContextOverloads {
// 内容整理到 'WebGLRenderingContext 对象'
}
[Exposed=(Window,Worker)]
interface WebGLRenderingContext {
// 内容整理到 'WebGLRenderingContext 对象'
};
WebGLRenderingContext includes WebGLRenderingContextBase;
WebGLRenderingContext includes WebGLRenderingContextOverloads;
[Exposed=(Window,Worker),
Constructor(DOMString type,
optional WebGLContextEventInit eventInit)]
interface WebGLContextEvent : Event {
readonly attribute DOMString statusMessage;
};
// EventInit is defined in the DOM4 specification.
dictionary WebGLContextEventInit : EventInit {
DOMString statusMessage = "";
};
WebGLRenderingContext 对象
属性数据
[Exposed=Window] readonly attribute (HTMLCanvasElement or OffscreenCanvas) canvas;
// 可以在 Web Work 上使用 canvas api
// 需要调用 canvas.transferControlToOffscreen() 将渲染权转移给后台线程
[Exposed=Worker] readonly attribute OffscreenCanvas canvas;
readonly attribute GLsizei drawingBufferWidth;
readonly attribute GLsizei drawingBufferHeight;
缓冲区相关方法
清理渲染缓冲区。
// 缓冲区类型
// 为 gl.clear 的参数
const GLenum DEPTH_BUFFER_BIT = 0x00000100;
const GLenum STENCIL_BUFFER_BIT = 0x00000400;
const GLenum COLOR_BUFFER_BIT = 0x00004000;
// 清理指定缓存内容, 可以通过或运算符一次清理多个缓冲区
// @param mask 颜色缓冲区(COLOR_BUFFER_BIT) | 深度缓冲区(DEPTH_BUFFER_BIT) | 模板缓冲区(STENCIL_BUFFER_BIT)
void clear(GLbitfield mask);
// 将指定缓冲区设置为指定的值(参数范围都是 0.0 - 1.0)
// clearColor 指定的值 默认 0.0, 0.0, 0.0, 0.0
// clearDepth 指定的值 默认 1.0
// clearStencil 指定的值 默认 0
void clearColor(GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha);
void clearDepth(GLclampf depth);
void clearStencil(GLint s);
绘制相关方法
绘制缓存中的顶点数据。
// 绘制的类型
// 为 gl.drawArrays、gl.drawElements 第一个参数
const GLenum POINTS = 0x0000;
const GLenum LINES = 0x0001;
const GLenum LINE_LOOP = 0x0002;
const GLenum LINE_STRIP = 0x0003;
const GLenum TRIANGLES = 0x0004;
const GLenum TRIANGLE_STRIP = 0x0005;
const GLenum TRIANGLE_FAN = 0x0006;
// 执行绘制, 按照mode参数指定的方式绘制图形
// @param model 绘制模式。
// @param first 指定从哪个定点开始绘制
// @param count 指定绘制需要用到多少个顶点
void drawArrays(GLenum mode, GLint first, GLsizei count);
// 执行绘制,按照mode参数制定的方式,根据绑定到 ELEMENT_ARRAY_BUFFER 的缓冲区中的顶点索引绘制图形
// @param model 绘制模式。
// @param count 指定绘制顶点的个数
// @param type 指定索引值数据类型。包括:UNSIGNED_BYTE、UNSIGNED_SHORT、UNSIGNED_INT
// @param offset 指定索引数组中绘制的偏移位置,以字节为单位
void drawElements(GLenum mode, GLsizei count, GLenum type, GLintptr offset);
着色器 attribute 相关
// 获取由 name 参数指定的 attribute 变量存储地址
// @param program 指定包含顶点或者片元着色器的程序对象
// @param name 获取其存储的 attribute 变量名称,最大长度256字节
[WebGLHandlesContextLoss] GLint getAttribLocation(WebGLProgram program, DOMString name);
// 绑定顶点索引到属性变量
// 使用缓冲区数据的时候需要用到的方法
// @param index 指定要绑定的通用顶点的索引 这个值直接赋值给 vertexAttribPointer 的 index 参数
// @param name 指定变量名
// 这里的 index 和 getAttribLocation 返回值是一样的
void bindAttribLocation(WebGLProgram program, GLuint index, DOMString name);
// 将数据传给由index参数指定的attribute变量
void vertexAttrib1f(GLuint index, GLfloat x);
void vertexAttrib2f(GLuint index, GLfloat x, GLfloat y);
void vertexAttrib3f(GLuint index, GLfloat x, GLfloat y, GLfloat z);
void vertexAttrib4f(GLuint index, GLfloat x, GLfloat y, GLfloat z, GLfloat w);
// 接收参数为 Float32Array 数组
void vertexAttrib1fv(GLuint index, Float32List values);
void vertexAttrib2fv(GLuint index, Float32List values);
void vertexAttrib3fv(GLuint index, Float32List values);
void vertexAttrib4fv(GLuint index, Float32List values);
着色器 uniform 相关
// 获取指定名称的 uniform 变量存储位置
// @param program 制定的包含顶点或者片元着色器的程序对象
// @param name 指定想要获取其存储位置的uniform变量名称 最大长度256字节
WebGLUniformLocation? getUniformLocation(WebGLProgram program, DOMString name);
// 将数据传给location指定的uniform变量
void uniform1f(WebGLUniformLocation? location, GLfloat x);
void uniform2f(WebGLUniformLocation? location, GLfloat x, GLfloat y);
void uniform3f(WebGLUniformLocation? location, GLfloat x, GLfloat y, GLfloat z);
void uniform4f(WebGLUniformLocation? location, GLfloat x, GLfloat y, GLfloat z, GLfloat w);
void uniform1i(WebGLUniformLocation? location, GLint x);
void uniform2i(WebGLUniformLocation? location, GLint x, GLint y);
void uniform3i(WebGLUniformLocation? location, GLint x, GLint y, GLint z);
void uniform4i(WebGLUniformLocation? location, GLint x, GLint y, GLint z, GLint w);
void uniform1fv(WebGLUniformLocation? location, Float32List v);
void uniform2fv(WebGLUniformLocation? location, Float32List v);
void uniform3fv(WebGLUniformLocation? location, Float32List v);
void uniform4fv(WebGLUniformLocation? location, Float32List v);
void uniform1iv(WebGLUniformLocation? location, Int32List v);
void uniform2iv(WebGLUniformLocation? location, Int32List v);
void uniform3iv(WebGLUniformLocation? location, Int32List v);
void uniform4iv(WebGLUniformLocation? location, Int32List v);
// @param 是否对矩阵进行转置 默认 false 在webgl中必须是false
void uniformMatrix2fv(WebGLUniformLocation? location, GLboolean transpose, Float32List value);
void uniformMatrix3fv(WebGLUniformLocation? location, GLboolean transpose, Float32List value);