APIs - 蓝紫开发接口一、画布初始化 二、程序接口三、资源接口四、用户交互一、画布初始化

蓝紫程序的一切都从唯一的全局变量 Lan 开始,我们通常是使用 Lan.canvasxx 方法初始化画布,然后开始绘制。

const canvas = Lan.canvasxx(width, height, options)

我们也可以将 widthheight 写在 options 中,比如:

const canvas = Lan.canvas({width:900, height:600, ...})

如果未指定 widthheight,我们会采用 Canvas 元素样式宽高,同时参考其 scale 属性:

<canvas scale="2" style="width:600;height:400"><canvas>

这时候,计算得到的宽度为 600 x 2 = 1200,高度为 400 x 2 = 800。这样的处理方式对于我们集成蓝紫程序到第三方平台进行自动宽高处理非常有帮助,具体请参考我们在 Codepen 上的例子:Lands Demo Program - 56

无论采用哪种渲染引擎初始化画布,返回的 canvas 对象都会有一些公共属性:

画布初始化接口的参数基本是都是 (width, height, options) 这样的形式,我们也可以将 widthheight 写在 options 参数里:

const canvas = Lan.canvasxx({
  width  : 900, 
  height : 600, 
  ...
})

每一种渲染引擎的画布初始化方法请参考对应的文档了解详情。

二、程序接口 async Lan.loop(callback, [maxframes])

该方法用于循环执行,通常用于渲染动画或执行其它重复操作,maxframes 控制最多循环次数,或者当 callback 函数返回 false 的时候也会结束循环。回调函数 callback 形式如下:

callback(time_elapsed, time_delta, frame_number, seconds_of_the_day)
Lan.log(msg)

写程序运行日志

async Lan.import(lib)

导入 JS 程序库,前提是该库必须是一个标准的 Module。比如 Lan.import('three') 用于引入 three.js 库。也可以通过 URL 地址导入外部 JS 库,比如:Lan.import('https://...')。以下是蓝紫缺省提供的 JS 库,可直接通过名称导入,名称不区分大小写:

三、资源接口 async Lan.file()

选择本地文件,比如,选择一个图像,然后可以使用该图像进行各种操作。返回文件对象(File)并附加如下属性和方法:

async Lan.colormap(url)

加载 colormap 资源,使用代码参考官方 Demo:Pixel Shader Colormaps。该函数返回一个数组:

const colors = [[r0, g0, b0], [r1, g1, b1], ... [r255, g255, b255]];
colors.get = (colval, [multiply = 1]) => {r, g, b};

其中,get 函数将 colval 映射为一个 {r, g, b},可以通过传入 multiply 对输出颜色调整为 rgb255 颜色。

async Lan.audio(url, [options = {play:true, loop:true}])

加载并播放音频文件,返回 Audio 对象,同时附加如下属性和方法:

async Lan.image(url)

加载图像,返回 Image 对象,并附加如下属性及方法:

async Lan.video(url, options = {mute:true, loop:true})

加载视频,返回 Video 对象,附加如下属性:

async Lan.camera(options = {})

打开摄像头,返回 Video 对象,附加如下属性:

通过 options 可以指定一些参数:

const camera = Lan.camera({width:1280, height:720})
const camera = Lan.camera({
  width: { min: 1280 },
  height: { min: 720 },
})
const camera = Lan.camera({
  width: { ideal: 1280 },
  height: { ideal: 720 },
})
四、用户交互 Lan.mouse(handler)

我们可以使用本接口为画布配置鼠标交互处理器,handler 是一个对象,提供各种事件的处理函数:

具体使用方法,请参考蓝紫 canvas2d 引擎的向导程序:交互式画布。事实上,我们也可以不提供 handler,而是将该接口的返回值保存起来,随时获取鼠标状态:

const mouse_tracker = Lan.mouse()
const data = mouse_tracker();
const down = data.down; // 0 or 1
const posx = data.posx; // x coordinate of the mouse position
const posy = data.posy; // y coordinate of the mouse position
... // do anything you want

当鼠标未按下并且在画布之外的时候,posx 以及 posy 均为 undefined。使用该方法的例子,请参考 canvasps 引擎的向导程序:粒子系统