图形像素线

🌐 Graphics Pixel Line

pixelLine 属性是 PixiJS Graphics API 的一个很棒的功能，它允许你创建无论缩放或缩放级别如何都保持 1 像素宽的线条。作为 Graphics API 的一部分，它为开发者提供了构建和描绘形状的所有 PixiJS 功能。这个功能对于实现清晰、像素完美的视觉效果特别有用，尤其是在复古风格或基于网格的游戏、技术绘图或用户界面渲染中。

🌐 The pixelLine property is a neat feature of the PixiJS Graphics API that allows you to create lines that remain 1 pixel thick, regardless of scaling or zoom level. As part of the Graphics API, it gives developers all the power PixiJS provides for building and stroking shapes. This feature is especially useful for achieving crisp, pixel-perfect visuals, particularly in retro-style or grid-based games, technical drawing, or UI rendering.

在本指南中，我们将深入探讨此属性的工作原理、其用例以及使用它时应注意的注意事项。

🌐 In this guide, we'll dive into how this property works, its use cases, and the caveats you should be aware of when using it.

---

如何使用 pixelLine？

🌐 How to use pixelLine?

这是一个简单的例子：

🌐 Here’s a simple example:

// Create a Graphics object and draw a pixel-perfect line
let graphics = new Graphics().moveTo(0, 0).lineTo(100, 100).stroke({ color: 0xff0000, pixelLine: true });

// Add it to the stage
app.stage.addChild(graphics);

// Even if we scale the Graphics object, the line remains 1 pixel wide
graphics.scale.set(2);

在这个例子中，无论你如何变换或缩放 Graphics 对象，红线在屏幕上始终会显示为 1 像素厚。

🌐 In this example, no matter how you transform or zoom the Graphics object, the red line will always appear 1 pixel thick on the screen.

---

为什么使用 pixelLine？

🌐 Why Use pixelLine?

像素完美的线条在各种场景中都非常有用。以下是一些常见的使用案例：

🌐 Pixel-perfect lines can be incredibly useful in a variety of scenarios. Here are some common use cases:

1. 复古或像素艺术游戏

🌐 1. Retro or Pixel Art Games

• 像素艺术游戏在保持清晰、精确的视觉效果方面依赖很大。pixelLine 属性确保线条不会模糊或与其他像素元素不一致地缩放。
• 示例：为基于瓦片的地图绘制像素精确的网格。

// Create a grid of vertical and horizontal lines
const grid = new Graphics();

// Draw 10 vertical lines spaced 10 pixels apart
// Draw vertical lines
for (let i = 0; i < 10; i++) {
  // Move to top of each line (x = i*10, y = 0)
  grid
    .moveTo(i * 10, 0)
    // Draw down to bottom (x = i*10, y = 100)
    .lineTo(i * 10, 100);
}

// Draw horizontal lines
for (let i = 0; i < 10; i++) {
  // Move to start of each line (x = 0, y = i*10)
  grid
    .moveTo(0, i * 10)
    // Draw across to end (x = 100, y = i*10)
    .lineTo(100, i * 10);
}

// Stroke all lines in white with pixel-perfect width
grid.stroke({ color: 0xffffff, pixelLine: true });

---

2. 用户界面和HUD元素

🌐 2. UI and HUD Elements

• 对于边框、分隔符或下划线等 UI 元素，一致的 1 像素厚度可提供专业、干净的外观。
• 示例：在菜单中绘制分隔线或在进度条边框中绘制分隔线。

// Create a separator line that will always be 1 pixel thick
const separator = new Graphics()
  // Start at x=0, y=50
  .moveTo(0, 50)
  // Draw a horizontal line 200 pixels to the right
  .lineTo(200, 50)
  // Stroke in green with pixel-perfect 1px width
  .stroke({ color: 0x00ff00, pixelLine: true });

---

3. 调试与原型设计

🌐 3. Debugging and Prototyping

• 使用像素精确的线条来调试布局、碰撞盒或网格。由于这些线条不会缩放，它们在开发过程中提供了一个一致的参考点。
• 示例：在基于物理的游戏中显示碰撞边界。

// Create a debug box with pixel-perfect stroke
const graphicsBox = new Graphics().rect(0, 0, 100, 100).stroke({ color: 0xff00ff, pixelLine: true });

/**
 * Updates the debug box to match the bounds of a given object
 * @param {Container} obj - The object to draw bounds for
 */
function drawDebugBounds(obj) {
  // Get the bounds of the object
  let bounds = obj.getBounds().rectangle;

  // Position and scale the debug box to match the bounds
  // this is faster than using `moveTo` and `lineTo` each frame!
  graphicsBox.position.set(bounds.x, bounds.y);
  graphicsBox.scale.set(bounds.width / 100, bounds.height / 100);
}

---

工作原理

🌐 How it works

当 pixelLine 设置为 true 时，这是通过 WebGL 或 WebGPU 的原生线条渲染方法在幕后实现的。

🌐 This is achieved under the hood using WebGL or WebGPU's native line rendering methods when pixelLine is set to true.

有趣的事实是，绘制像素线实际上比绘制普通直线更快。这是由于两个主要因素：

🌐 Fun fact its actually faster to draw a pixel line than a regular line. This is because of two main factors:

1. 更简单的绘图过程：在 PixiJS 中常规线条（当 pixelLine 为 false 时）需要额外的步骤来绘制。PixiJS 必须确定线条的粗细，并创建一个看起来像线条但实际上由三角形组成的形状。
2. 直接线条绘制：使用 pixelLine 时，我们可以告诉显卡“直接从点 A 画到点 B”，它就会准确地执行。这比创建和填充形状要简单得多，也更快。

把它想象成在纸上画线——pixelLine就像用钢笔画一条直线，而普通线就像不得不小心地填充一个细长的矩形。用钢笔的方法自然更快更简单！

🌐 Think of it like drawing a line on paper - pixelLine is like using a pen to draw a straight line, while regular lines are like having to carefully color in a thin rectangle. The pen method is naturally faster and simpler!

注意事项和陷阱

🌐 Caveats and Gotchas

虽然 pixelLine 属性非常有用，但有一些限制和需要注意的事项：

🌐 While the pixelLine property is incredibly useful, there are some limitations and things to keep in mind:

1. 它只有1像素厚，就这样！

🌐 1. Its 1px thick, thats it!

• 线条始终为 1px 粗细，无法更改，因为它使用 GPU 来绘制线条。

2. 硬件可能会渲染不同的效果

🌐 2. Hardware may render differently

• 由于不同的 GPU 和图形硬件在处理线条光栅化时存在差异，因此它们可能会略微不同地渲染线条。例如，一些 GPU 可能会略微不同地定位线条或应用不同的抗锯齿技术。这是 GPU 线条渲染的固有限制，并且超出了 PixiJS 的控制范围。

4. 缩放行为

🌐 4. Scaling Behavior

• 虽然线条粗细保持不变，但其他属性（例如位置或起止点）仍会受到缩放的影响。如果与其他缩放对象结合使用，有时可能会产生意想不到的结果。这是一个特性，不是错误 :)

示例：具有像素精确描边的框

🌐 Example: Box with Pixel-Perfect Stroke

这是一个带有像素精确描边的填充盒子示例。盒子本身可以缩放和增长，但描边保持 1 像素宽：

🌐 Here's an example of a filled box with a pixel-perfect stroke. The box itself scales and grows, but the stroke remains 1 pixel wide:

// Create a Graphics object and draw a filled box with a pixel-perfect stroke
let box = new Graphics().rect(0, 0, 100, 100).fill('white').stroke({ color: 0xff0000, pixelLine: true });

// Add it to the stage
app.stage.addChild(box);

// Scale the box
box.scale.set(2);

在此示例中，蓝色框在缩放时会变大，但红色笔触保持 1 像素厚度，无论缩放比例如何，都能提供清晰的轮廓。

🌐 In this example, the blue box grows as it scales, but the red stroke remains at 1 pixel thickness, providing a crisp outline regardless of the scaling.

---

何时避免使用 pixelLine

🌐 When to Avoid Using pixelLine

• **你想要一条不是1像素厚的线：**不要使用pixelLine。
• **你想要线条缩放：**不要使用 pixelLine

---

结论

🌐 Conclusion

pixelLine 属性在 PixiJS 工具箱中对开发者非常有用，尤其是那些希望创建在变换下仍保持一致的清晰、像素完美线条的开发者。通过了解它的优势和局限性，你可以将其融入到你的项目中，从而在视觉和功能元素上都获得干净、专业的效果。

🌐 The pixelLine property is a super useful to have in the PixiJS toolbox for developers looking to create sharp, pixel-perfect lines that remain consistent under transformation. By understanding its strengths and limitations, you can incorporate it into your projects for clean, professional results in both visual and functional elements.