# qq.createCanvas

# Canvas qq.createCanvas()

创建一个画布对象。首次调用创建的是显示在屏幕上的画布,之后调用创建的都是离屏画布。

# 返回值

# Canvas

画布对象

# Canvas

画布对象

# 属性

# number width

画布的宽度

# number height

画布的高度

# 方法

# string Canvas.toTempFilePath(Object object)

将当前 Canvas 保存为一个临时文件。

# RenderingContext Canvas.getContext(string contextType, Object contextAttributes)

获取画布对象的绘图上下文

# string Canvas.toDataURL()

把画布上的绘制内容以一个 data URI 的格式返回

# .toTempFilePathSync

# Canvas.toTempFilePathSync(Object object)

Canvas.toTempFilePath 的同步版本

# 参数

# Object object
属性 类型 默认值 必填 说明
x number 0 截取 canvas 的左上角横坐标
y number 0 截取 canvas 的左上角纵坐标
width number canvas 的宽度 截取 canvas 的宽度
height number canvas 的高度 截取 canvas 的高度
destWidth number canvas 的宽度 目标文件的宽度,会将截取的部分拉伸或压缩至该数值
destHeight number canvas 的高度 目标文件的高度,会将截取的部分拉伸或压缩至该数值
fileType string png 目标文件的类型
quality number 1.0 jpg图片的质量,仅当 fileType 为 jpg 时有效。取值范围为 0.0(最低)- 1.0(最高),不含 0。不在范围内时当作 1.0

object.fileType 的合法值

说明
jpg jpg 文件
png png 文件

# 示例代码

Canvas.toTempFilePath

canvas.toTempFilePath({
x: 10,
y: 10,
width: 200,
height: 150,
destWidth: 400,
destHeight: 300,
success: (res) => {
qq.shareAppMessage({
imageUrl: res.tempFilePath
})
}
})
1
2
3
4
5
6
7
8
9
10
11
12
13

Canvas.toTempFilePathSync

const tempFilePath = canvas.toTempFilePathSync({
x: 10,
y: 10,
width: 200,
height: 150,
destWidth: 400,
destHeight: 300
})
qq.shareAppMessage({
imageUrl: tempFilePath
})
1
2
3
4
5
6
7
8
9
10
11

# .toTempFilePath

# string Canvas.toTempFilePath(Object object)

将当前 Canvas 保存为一个临时文件。

# 参数

# Object object
属性 类型 默认值 必填 说明
x number 0 截取 canvas 的左上角横坐标
y number 0 截取 canvas 的左上角纵坐标
width number canvas 的宽度 截取 canvas 的宽度
height number canvas 的高度 截取 canvas 的高度
destWidth number canvas 的宽度 目标文件的宽度,会将截取的部分拉伸或压缩至该数值
destHeight number canvas 的高度 目标文件的高度,会将截取的部分拉伸或压缩至该数值
fileType string png 目标文件的类型
quality number 1.0 jpg图片的质量,仅当 fileType 为 jpg 时有效。取值范围为 0.0(最低)- 1.0(最高),不含 0。不在范围内时当作 1.0
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
complete function 接口调用结束的回调函数(调用成功、失败都会执行)

object.fileType 的合法值

说明
jpg jpg 文件
png png 文件

# 返回值

# string

canvas 生成的临时文件路径

# 示例代码

Canvas.toTempFilePath

canvas.toTempFilePath({
x: 10,
y: 10,
width: 200,
height: 150,
destWidth: 400,
destHeight: 300,
success: (res) => {
qq.shareAppMessage({
imageUrl: res.tempFilePath
})
}
})
1
2
3
4
5
6
7
8
9
10
11
12
13

Canvas.toTempFilePathSync

const tempFilePath = canvas.toTempFilePathSync({
x: 10,
y: 10,
width: 200,
height: 150,
destWidth: 400,
destHeight: 300
})
qq.shareAppMessage({
imageUrl: tempFilePath
})
1
2
3
4
5
6
7
8
9
10
11

# .toDataURL

# string Canvas.toDataURL()

把画布上的绘制内容以一个 data URI 的格式返回

# 返回值

# string

data URI 格式的字符串

# .getContext

# RenderingContext Canvas.getContext(string contextType, Object contextAttributes)

获取画布对象的绘图上下文

# 参数

# string contextType

上下文类型

contextType 的合法值

说明
2d 2d 绘图上下文
webgl webgl 绘图上下文
webgl2 webgl2 绘图上下文

webgl2支持情况:Android 从QQ版本8.9.88开始支持,需要在game.json手动配置属性:enableWebgl2Context: true开启; iOS在Unity游戏直接支持,非Unity游戏需要开启高性能模式支持。

# Object contextAttributes

webgl 上下文属性,仅当 contextType 为 webgl 时有效

属性 类型 默认值 必填 说明
antialias boolean false 表示是否抗锯齿
preserveDrawingBuffer boolean false 表示是否绘图完成后是否保留绘图缓冲区
antialiasSamples number 2 抗锯齿样本数。最小值为 2,最大不超过系统限制数量,仅 iOS 支持

# 返回值

# RenderingContext

绘图上下文

# RenderingContext

画布对象的绘图上下文。

  • 通过 Canvas.getContext('2d') 接口可以获取 CanvasRenderingContext2D 对象,实现了 HTML Canvas 2D Context 定义的大部分属性、方法。
  • 通过 Canvas.getContext('webgl') 接口可以获取 WebGLRenderingContext 对象,实现了 WebGL 1.0 定义的所有属性、方法、常量。
  • 通过 Canvas.getContext('webgl2') 接口可以获取 WebGL2RenderingContext 对象,实现了 WebGL 2.0 定义的所有属性、方法、常量。

# 2d 接口支持情况

iOS/Android 不支持的 2d 属性和接口

  • globalCompositeOperation 不支持以下值: source-in source-out destination-atop lighter copy。如果使用,不会报错,但是将得到与预期不符的结果。
  • isPointInPath
  • isPointInStroke
  • setLineDash
  • getLineDash
  • lineDashOffset
  • shadowColor
  • shadowBlur
  • shadowOffsetX
  • shadowOffsetY

# WebGL 接口支持情况

压缩纹理的支持

  • iOS 支持 pvr 格式
  • Android 支持 etc1 格式

# WebGL 扩展接口

为提升3D游戏性能,QQ小游戏为 WebGLContext 新增了以下接口,自基础库1.8.0开始支持。 LayaAir 2.3.0版本开始支持这些接口。

# .createArrayBufferRef

# ArrayBufferRef WebGLContext.createArrayBufferRef(ArrayBuffer arrayBuffer, number type, boolean syncRender)

创建ArrayBufferRef,把ArrayBuffer作为参数传入,调用此函数后,ArrayBuffer便有一个_ptrID的属性,Runtime中通过此ID便可以找到ArrayBuffer对应的数据区

# 参数

# ArrayBuffer arrayBuffer

传入想要和 Runtime 映射的 arrayBuffer

# number type

0代表纯数据区,1代表指令流CommandEncoder

# boolean syncRender

是否同步到渲染线程,目前只有单线程,值无效

# 返回值

# ArrayBufferRef

ArrayBuffer 的扩展,增加了_ptrID 属性

# .createArrayBufferRefs

# ArrayBufferRef WebGLContext.createArrayBufferRefs(ArrayBuffer arrayBuffer, number type, boolean syncRender, number refType)

一个ArrayBuffer可以对应多个ID,也就是可以对应多块数据,以便应对在一帧内多次修改ArrayBuffer的值,并把不同阶段的值上传显卡

# 参数

# ArrayBuffer arrayBuffer

传入想要和 Runtime 映射的 arrayBuffer

# number type

0代表纯数据区,1代表指令流CommandEncoder

# boolean syncRender

是否同步到渲染线程,目前只有单线程,值无效

# number refType

arrayBuffer 传递给 runtime 的方式,0代表引用,1为拷贝

# 返回值

# ArrayBufferRef

ArrayBuffer 的扩展,增加了_ptrID 属性

# .updateArrayBufferRef

# WebGLContext.updateArrayBufferRef(number bufferID, boolean isSyncToRender, ArrayBuffer arrayBuffer)

当 ArrayBuffer 的 Obj 发生变化,需要重新绑定到 ID 上,可调用此函数进行更新

# 参数

# number bufferID

ArrayBufferRef 的_ptrID

# boolean isSyncToRender

是否同步到渲染线程,目前只有单线程,值无效

# ArrayBuffer arrayBuffer

原生 ArrayBuffer 实例

# .updateAnimationNodeWorldMatix

# WebGLContext.updateAnimationNodeWorldMatix(TypedArray locPosition, TypedArray locRotation, TypedArray locScaling, TypedArray parentIndices, TypedArray outWorldMatrix)

更新骨骼动画并计算每块骨骼的 worldMatrix

# 参数

# TypedArray locPosition

所有 bone 的 local position,值类型为 Float32Array

# TypedArray locRotation

所有 bone 的 local rotation,值类型为 Float32Array

# TypedArray parentIndices

所有 bone 的父节点 ID,值类型为 Uint16Array

# TypedArray outWorldMatrix

所有 bone 计算好的 worldMatrix,值类型为 Float32Array

# .computeSubSkinnedData

# boolean WebGLContext.computeSubSkinnedData(TypedArray worldMatrixs, TypedArray worldMatrixIndex, TypedArray inverseBindPoses, TypedArray boneIndices, TypedArray bindPoseIndices, TypedArray resultData)

通过骨骼的世界矩阵和 mesh 的 BindPoses ,计算出针对于该 Mesh 的蒙皮矩阵

# 参数

# TypedArray worldMatrixs

所有bone的worldMatrix,值类型为Float32Array

# TypedArray worldMatrixIndex

所有bone的worldMatrix的索引位置,值类型为Uint16Array

# TypedArray inverseBindPoses

所有Bone的BindPose的逆矩阵,值类型为Float32Array

# TypedArray boneIndices

该Mesh收到哪些骨骼影响的骨骼ID,值类型为Uint16Array

# TypedArray bindPoseIndices

所有Bone的BindPose的逆矩阵的索引位置,值类型为Uint16Array

# TypedArray resultData

出参,计算好的结果,针对于该Mesh收到骨骼影响的矩阵信息

# 返回值

# boolean

是否计算成功

#

# .evaluateClipDatasRealTime

# WebGLContext.evaluateClipDatasRealTime(KeyframeNodeList nodes, number playCurTime, TypedArray realTimeCurrentFrameIndexes, boolean additive, boolean frontPlay)

计算当前动画帧数据

# 参数

# KeyframeNodeList nodes

KeyframeNodeList 节点队列

# number playCurTime

当前播放时间

# TypedArray realTimeCurrentFrameIndexes

实时当前帧索引

# boolean additive

是否是叠加模式

# boolean frontPlay

是否正向播放

# .culling

# number WebGLContext.culling(TypedArray boundFrustumBuffer, TypedArray cullingBuffer, TypedArray cullingBufferIndices, number cullingCount, TypedArray cullingBufferResult)

3D裁剪函数

# 参数

# TypedArray boundFrustumBuffer

摄影机视锥的信息

# TypedArray cullingBuffer

所有物体的包围盒、包围球信息

# TypedArray cullingBufferIndices

物体包围体的索引值

# number cullingCount

裁剪的个数

# TypedArray cullingBufferResult

是否在视锥范围的标志,cullingBufferResult[i]==1为可见,==0为不可见

# 返回值

# number

裁剪数量

# .createCommandEncoder

# GLCommandEncoder WebGLContext.createCommandEncoder(number reserveSize, number adjustSize, bool isSyncToRenderThread)

创建 GLCommandEncoder 类的实例

# 参数

# number reserveSize

预分配 Buffer 的 size

# number adjustSize

当实际的 bufferSize 超过预分配的 size 时会自动扩充,每次扩充的 size

# bool isSyncToRenderThread

buffer 是否同步到渲染线程,目前单线程模式值可忽略

# 返回值

# GLCommandEncoder

返回 GLCommandEncoder 实例

# .uploadShaderUniforms

# WebGLContext.uploadShaderUniforms(GLCommandEncoder encoder, ArrayBuffer data, number type)

批量上传 Uniform

# 参数

# GLCommandEncoder encoder

uniform 的指令集

# ArrayBuffer data

指令集对应的参数数据区

# number type

0为按照 Data 的 ID 传入,1为直接拷贝 Data 的值

# .uniformMatrix2fvEx

# WebGLContext.uniformMatrix2fvEx

uniformMatrix2fv 的扩展,参数和标准 uniformMatrix2fv 保持一致,区别在于如果 value 已经有了 _ptrID,调用 runtime 的时候,只用传入 ID 即可

# .uniformMatrix3fvEx

# WebGLContext.uniformMatrix3fvEx

uniformMatrix3fv 的扩展,参数和标准 uniformMatrix2fv 保持一致,区别在于如果 value 已经有了 _ptrID,调用 runtime 的时候,只用传入 ID 即可

# .uniformMatrix4fvEx

# WebGLContext.uniformMatrix4fvEx

uniformMatrix4fv 的扩展,参数和标准 uniformMatrix2fv 保持一致,区别在于如果 value 已经有了 _ptrID,调用 runtime 的时候,只用传入 ID 即可