PIXI入门-PIXI文档翻译(1)

1、创建渲染器和舞台
第一步是创建一个矩形显示区域，您可以开始在其上显示图像。Pixi有一个 renderer对象为你创建这个。它自动生成一个HTML <canvas>元素，并计算如何在画布上显示您的图像。然后需要创建一个特殊的Pixi Container对象称为stage。正如你将看到的，这个阶段对象将被用作根容器，包含你想要Pixi显示的所有东西。

这里是你需要写的代码来创建renderer 和stage。将此代码添加到您的HTML文档的<script>标签之间：

//Create the renderer
var renderer = PIXI.autoDetectRenderer(256, 256);

//Add the canvas to the HTML document
document.body.appendChild(renderer.view);

//Create a container object called the `stage`
var stage = new PIXI.Container();

//Tell the `renderer` to `render` the `stage`
renderer.render(stage);

这是你需要写的最基本的代码，以开始使用Pixi。它生成一个黑色的256像素乘256像素的画布元素，并将其添加到您的HTML文档。以下是运行此代码时在浏览器中显示的内容。

Yay，一个黑色的正方形！

Pixi的autoDetectRenderer方法确定是否使用Canvas绘图API或WebGL来渲染图形，这取决于可用的。它的第一个和第二个参数是画布的宽度和高度。但是，您可以包括可选的第三个参数以及可以设置的一些附加值。这第三个参数是一个对象字面量，这里如何使用它设置抗锯齿，透明度和分辨率：

renderer =  PIXI。autoDetectRenderer（
   256，256，
  {antialias : false,transparent: false,resolution: 1 }
）;

第三个参数（选项对象）是可选的 - 如果你对Pixi的默认设置感到满意，你可以放弃它，通常不需要改变它们。（但是，如果需要，请参阅Pixi的有关Canvas Renderer 和 WebGLRenderer的文档 以获取更多信息。）

这些选项做什么？

{antialias: false, transparent: false, resolution: 1}

antialias平滑字体和图形基元的边缘。（WebGL抗锯齿不是在所有平台上都可用，因此您需要在游戏的目标平台上测试此功能。）transparent使画布背景透明。resolution使得更容易使用不同分辨率和像素密度的显示器。设置分辨率有点超出本教程的范围，但检查Mat Grove 关于如何使用resolution所有细节的解释。但通常，resolution 对于大多数项目，只保持在1，你会没事的。

（注意：渲染器有一个额外的，第四个选项preserveDrawingBuffer，默认为false。设置它的唯一原因true是，如果你需要调用Pixi的专门的dataToURL 方法在WebGL画布上下文）。

Pixi的渲染器对象默认使用WebGL，这是很好的，因为WebGL是令人难以置信的快，让你使用一些壮观的视觉效果，你会学到所有关于未来。但是如果你需要强制Canvas绘图API渲染通过WebGL，你可以这样做：

renderer = new PIXI.CanvasRenderer(256, 256);

只有前两个参数是必需的：width和height。

你可以强制WebGL渲染这样：

renderer = new PIXI.WebGLRenderer(256, 256);

该renderer.view对象只是一个普通的老式普通的<canvas> 对象，所以你可以控制它，你将控制其他任何画布对象以同样的方式。下面是如何给画布一个可选的虚线边框：

renderer.view.style.border = "1px dashed black";

如果您需要在创建后更改画布的背景颜色，请将renderer对象的backgroundColor属性设置为任何十六进制颜色值：

renderer.backgroundColor = 0x061639;

如果要找到的宽度或高度renderer，请使用 renderer.view.width和renderer.view.height。

（重要：虽然stage也有width和height性能，他们并不指渲染窗口的大小舞台的，width而height 只是告诉你通过你把它里面的东西所占据的区域-更多的在前面！）

要更改画布的大小，请使用renderer's' resize 方法，并提供任何新值width和height值。但是，要确保画布的大小调整为与分辨率匹配，请设置autoResize 为true。

renderer.autoResize = true;
renderer.resize(512, 512);

如果要使画布填满整个窗口，您可以应用此CSS样式，并将渲染器的大小调整为浏览器窗口的大小。

renderer.view.style.position = "absolute";
renderer.view.style.display = "block";
renderer.autoResize = true;
renderer.resize(window.innerWidth, window.innerHeight);

但是，如果你这样做，请确保你也设置默认填充和边距为0在所有的HTML元素与此位的CSS代码：

<style> *{ padding:0;margin:0 } </style>

（上面的代码中的星号*是CSS“通用选择器”，它只是意味着“HTML文档中的所有标签”）。

如果您希望画布按比例缩放到任何浏览器窗口大小，则可以使用此自定义scaleToWindow函数。

2、Pixi Sprite
在上一节中，您学习了如何创建一个stage对象，如下所示：

var stage =  new  PIXI.Container();

该stage是Pixi的Container对象。你可以把一个容器看成是一个空的盒子，它将组合在一起并存储你放在里面的任何东西。stage我们创建的对象是你场景中所有可见东西的根容器。Pixi要求你有一个根容器对象，因为renderer需要渲染的东西：

renderer.render(stage);

无论你放在里面stage将会呈现在canvas上。现在stage是空的，但很快我们就要开始把东西放在里面。

（注意：你可以给你的根容器任何你喜欢的名字，调用它 scene或者root如果你喜欢这个名字 stage只是一个古老但有用的约定，我们将在本教程中坚持）

那么你把什么放在舞台上？特殊图像对象称为 精灵。Sprite基本上只是你可以用代码控制的图片。您可以控制它们的位置，大小和其他一些对于制作交互式和动画图形有用的属性。学习制作和控制精灵是真正的最重要的事情，学习使用Pixi。如果你知道如何制作精灵，并将它们添加到舞台上，你只是一个小步骤，开始制作游戏。

Pixi有一个Sprite类，是一个多才多艺的方式来制作游戏精灵。有三种主要方法来创建它们：

(1)从单个图像文件。
(2)从图块上的子图像。tileset是一个单一的大图片，包括您在游戏中需要的所有图片。
(3)从纹理地图集（定义图像集大小和位置的JSON文件）。

你将学习所有三种方法，但在你做之前，让我们先了解你需要了解的图像，然后才能用Pixi显示它们。

将图像加载到纹理缓存中
因为Pixi使用WebGL在GPU上渲染图像，所以图像需要采用GPU可以处理的格式。WebGL准备好的图像称为纹理。在使sprite显示图像之前，您需要将普通图像文件转换为WebGL纹理。为了保持一切工作的快速和有效的底层，Pixi使用纹理缓存来存储和引用你的sprites将需要的所有纹理。纹理的名称是与它们所引用的图像的文件位置匹配的字符串。这意味着如果你有一个纹理加载"images/cat.png"，你可以在纹理缓存中找到它，如下所示：

PIXI.utils.TextureCache["images/cat.png"];

纹理存储在一个WebGL兼容的格式，这是有效的Pixi的渲染器工作。然后你可以使用Pixi的Sprite类使用纹理创建一个新的sprite。

var texture = PIXI.utils.TextureCache["images/anySpriteImage.png"];
var sprite = new PIXI.Sprite(texture);

但是如何加载图像文件并将其转换为纹理？使用Pixi的内置loader对象。

Pixi的强大的loader对象是所有你需要加载任何类型的图像。以下是如何使用它来加载图像并调用setup在图像加载完成后调用的函数：

PIXI.loader
  .add("images/anyImage.png")
  .load(setup);

function setup() {
  //This code will run when the loader has finished loading the image
}

PIXI开发团队建议 ，如果你使用的装载机，应通过引用纹理在创建精灵loader的resources对象，就像这样：

var sprite = new PIXI.Sprite(
  PIXI.loader.resources["images/anyImage.png"].texture
);

这里有一些完整的代码示例，您可以写入以加载图像，调用setup函数，并从加载的图像创建sprite：

PIXI.loader
  .add("images/anyImage.png")
  .load(setup);

function setup() {
  var sprite = new PIXI.Sprite(
    PIXI.loader.resources["images/anyImage.png"].texture
  );
}

您可以通过使用可链接的add方法列出来加载多个图像，如下所示：

PIXI.loader
  .add("images/imageOne.png")
  .add("images/imageTwo.png")
  .add("images/imageThree.png")
  .load(setup);

更好的是，只需列出所有要加载到单个add方法中的数组中的文件，如下所示：

PIXI.loader
  .add([
    "images/imageOne.png",
    "images/imageTwo.png",
    "images/imageThree.png"
  ])
  .load(setup);

该loader还可以让你加载JSON文件，您将在后面了解到。

3、显示sprites
加载图像并使用它来制作精灵后，还需要做两件事，然后才能在画布上看到它：

-1。你需要精灵添加到陂溪的stage与stage.addChild方法，如下：

stage.addChild(cat);

舞台是容纳所有精灵的主要容器。

-2。你需要告诉Pixi的renderer渲染舞台。

renderer.render(stage);

在你做这两件事之前，你的精灵都不会显示。

在我们继续之前，让我们来看一个如何使用刚才学到的内容显示单个图像的实际示例。在examples/images 文件夹中，你会发现一个64×64像素的PNG图像的一只猫。


这里是所有的JavaScript代码，你需要加载图像，创建一个sprite，并显示在Pixi的舞台上：

var stage = new PIXI.Container(),
    renderer = PIXI.autoDetectRenderer(256, 256);
document.body.appendChild(renderer.view);

//Use Pixi's built-in `loader` object to load an image
PIXI.loader
  .add("images/cat.png")
  .load(setup);

//This `setup` function will run when the image has loaded
function setup() {

  //Create the `cat` sprite from the texture
  var cat = new PIXI.Sprite(
    PIXI.loader.resources["images/cat.png"].texture
  );

  //Add the cat to the stage
  stage.addChild(cat);

  //Render the stage   
  renderer.render(stage);
}

运行此代码时，您会看到以下内容：



现在我们到这里了！
如果你需要从舞台上删除一个精灵，使用removeChild方法：

stage.removeChild(anySprite)

但通常设置sprite的visible属性false将是一个更简单和更有效的方式使sprites消失。

anySprite.visible = false;

使用别名
您可以通过为您经常使用的Pixi对象和方法创建简短形式的别名，为自己节省一些打字并使代码更具可读性。例如，PIXI.utils.TextureCache键入太多了？我想是这样，特别是在一个大项目，你可以使用它几十次。所以，创建一个较短的别名指向它，像这样：

var TextureCache = PIXI.utils.TextureCache

然后，使用别名代替原始，像这样：

var texture = TextureCache["images/cat.png"];

除了让你写更简洁的代码，使用别名还有一个额外的好处：它有助于略微缓冲你的Pixi经常变化的API。如果Pixi的API在未来的版本改变 - 这将！ - 你只需要更新这些别名到Pixi对象和方法在一个地方，在程序的开始，而不是每个实例，他们在整个代码中使用。所以当Pixi的开发团队决定他们想要重新排列家具时，你会比他们领先一步！

为了看看如何做到这一点，让我们重写我们写的代码来加载一个图像并显示它，使用别名对所有Pixi对象和方法。

//Aliases
var Container = PIXI.Container,
    autoDetectRenderer = PIXI.autoDetectRenderer,
    loader = PIXI.loader,
    resources = PIXI.loader.resources,
    Sprite = PIXI.Sprite;

//Create a Pixi stage and renderer and add the 
//renderer.view to the DOM
var stage = new Container(),
    renderer = autoDetectRenderer(256, 256);
document.body.appendChild(renderer.view);

//load an image and run the `setup` function when it's done
loader
  .add("images/cat.png")
  .load(setup);

function setup() {

  //Create the `cat` sprite, add it to the stage, and render it
  var cat = new Sprite(resources["images/cat.png"].texture);  
  stage.addChild(cat);
  renderer.render(stage);
}

本教程中的大多数示例将使用跟随此相同模型的Pixi对象的别名。除非另有说明，否则您可以假设所有代码示例都使用类似这样的别名。

这是所有你需要知道开始加载图像和创建精灵。

4、一点点关于装载进度loading的东西

我上面显示的格式是我建议您使用作为加载图像和显示精灵的标准模板。所以，你可以安全地忽略接下来的几个段落，直接跳到下一节“定位精灵”。但Pixi的loader对象是相当复杂的，包括一些功能，你应该注意，即使你不使用它们定期。让我们看看一些最有用的。

从普通的JavaScript Image对象或Canvas创建sprite

为了优化和效率，最好从已经预先加载到Pixi的纹理缓存中的纹理创建sprite。但是如果由于某种原因你需要从一个常规JavaScript Image 对象创建一个纹理 ，你可以使用Pixi BaseTexture和Texture 类：

var base = new PIXI.BaseTexture(anyImageObject),
    texture = new PIXI.Texture(base),
    sprite = new PIXI.Sprite(texture);

你可以使用，BaseTexture.fromCanvas如果你想从任何现有的canvas元素做一个纹理：

var base = new PIXI.BaseTexture.fromCanvas(anyCanvasElement),

如果要更改sprite正在显示的纹理，请使用 texture属性。将其设置为任何Texture对象，如下所示：

anySprite.texture = PIXI.utils.TextureCache["anyTexture.png"];

你可以使用这种技术交互式改变精灵的外观，如果在游戏中发生重大事情。

为加载文件指定名称

可以为要加载的每个资源分配唯一的名称。只需提供名称（字符串）作为add方法中的第一个参数 。例如，下面是如何命名一个猫的图像 catImage。

PIXI.loader
  .add("catImage", "images/cat.png")
  .load(setup);

这将创建称为对象catImage在loader.resources。这意味着您可以通过引用catImage对象来创建sprite ，如下所示：

var cat = new PIXI.Sprite(PIXI.loader.resources.catImage.texture);

但是，我建议您不要使用此功能！这是因为你必须记住你给每个加载的文件的所有名称，以及确保你不会不小心使用同一个名称多次。使用文件路径名，就像我们在前面的例子中做的一样，它更容易出错。

监控负载进度

Pixi的加载器有一个特殊的progress事件，将调用一个可定制的函数，每次加载文件时运行。progress事件被称为 loader的on方法，就像这样：

PIXI.loader.on("progress", loadProgressHandler);

下面是如何将on方法包含在加载链中，以及在loadProgressHandler每次加载文件时调用用户可定义的函数

PIXI.loader.on("progress", loadProgressHandler);

PIXI.loader
  .add([
    "images/one.png",
    "images/two.png",
    "images/three.png"
  ])
  .on("progress", loadProgressHandler)
  .load(setup);

function loadProgressHandler() {
  console.log("loading"); 
}

function setup() {
  console.log("setup");
}

每次加载其中一个文件时，progress事件将调用 loadProgressHandler在控制台中显示“加载”。当所有三个文件都加载后，setup 函数将运行。这里是控制台中上面的代码的输出：

loading
loading
loading
setup

这是整洁，但它变得更好。您还可以准确地确定已加载的文件以及当前加载的文件的百分比。你可以通过添加可选的loader和 resource参数来做到这一点loadProgressHandler，像这样：

function loadProgressHandler(loader, resource) { //...

然后，您可以使用resource.url查找当前加载的文件。（resource.name如果要查找可能已分配给文件的可选名称，请使用此选项作为方法的第一个参数 add。）您可以使用loader.progress查找当前加载的总资源的百分比。这里有一些代码。

PIXI.loader
  .add([
    "images/one.png",
    "images/two.png",
    "images/three.png"
  ])
  .on("progress", loadProgressHandler)
  .load(setup);

function loadProgressHandler(loader, resource) {

  //Display the file `url` currently being loaded
  console.log("loading: " + resource.url); 

  //Display the precentage of files currently loaded
  console.log("progress: " + loader.progress + "%"); 

  //If you gave your files names as the first argument 
  //of the `add` method, you can access them like this
  //console.log("loading: " + resource.name);
}

function setup() {
  console.log("All files loaded");
}

以下是代码在运行时显示在控制台中的代码：

loading: images/one.png
progress: 33.333333333333336%
loading: images/two.png
progress: 66.66666666666667%
loading: images/three.png
progress: 100%
All files loaded

这真的很酷，因为你可以使用它作为创建加载进度条的基础。

（注意：您可以访问 resource对象的其他属性resource.error将告诉您尝试加载文件时发生的任何可能的错误，resource.data让您访问文件的原始二进制数据。）

更多关于Pixi的装载机

Pixi的加载器是可笑的功能丰富和可配置。让我们快速浏览一下它的用法，让你开始。

加载器的chainable add方法需要4个基本参数：

add(name, url, optionObject, callbackFunction)

下面是加载器的源代码文档对这些参数的说明：

name（string）：要加载的资源的名称。如果没有通过，url则使用。
url（string）：这个资源的url，相对于baseUrl加载器的。
options（object literal）：加载的选项。
options.crossOrigin（Boolean）：请求是否是跨源的？默认值是自动确定。
options.loadType：资源应该如何加载？默认值为Resource.LOAD_TYPE.XHR。
options.xhrType：使用XHR时应如何解释加载的数据？默认值为Resource.XHR_RESPONSE_TYPE.DEFAULT
callbackFunction：当此特定资源完成加载时调用的函数。

这些参数中唯一需要的参数是url（要加载的文件）。

下面是一些您可以使用该add 方法加载文件的方法的示例。这些第一个是文档称为加载器的“正常语法”：

.add('key', 'http://...', function () {})
.add('http://...', function () {})
.add('http://...')

这些都是加载器的“对象语法”的例子：

.add({
  name: 'key2',
  url: 'http://...'
}, function () {})

.add({
  url: 'http://...'
}, function () {})

.add({
  name: 'key3',
  url: 'http://...'
  onComplete: function () {}
})

.add({
  url: 'https://...',
  onComplete: function () {},
  crossOrigin: true
})

您还可以将add对象或网址或两者的数组传递给方法：

.add([
  {name: 'key4', url: 'http://...', onComplete: function () {} },
  {url: 'http://...', onComplete: function () {} },
  'http://...'
]);

（注：如果你需要重置加载器加载一个新的批处理文件，调用加载器的reset方法：PIXI.loader.reset();）

Pixi的加载器有更多的高级功能，包括选项，让您加载和解析所有类型的二进制文件。这不是你需要做的日常工作，超出了本教程的范围，所以请确保检查加载器的GitHub存储库，了解更多信息。