Skip to main content

图形像素线

¥Graphics Pixel Line

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

¥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. 复古或像素艺术游戏​

¥ Retro or Pixel Art Games

  • 像素艺术游戏严重依赖于保持清晰、精确的视觉效果。pixelLine 属性可确保线条不会模糊或与其他像素元素不一致地缩放。

    ¥Pixel art games rely heavily on maintaining sharp, precise visuals. The pixelLine property ensures that lines do not blur or scale inconsistently with other pixel elements.

  • 示例：为基于图块的地图绘制像素完美的网格。

    ¥Example: Drawing pixel-perfect grids for tile-based maps.


// 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. UI 和 HUD 元素​

¥ UI and HUD Elements

  • 对于边框、分隔符或下划线等 UI 元素，一致的 1 像素厚度可提供专业、干净的外观。

    ¥For UI elements such as borders, separators, or underlines, a consistent 1-pixel thickness provides a professional, clean look.

  • 示例：在菜单或进度条边框中绘制分隔线。

    ¥Example: Drawing a separator line in a menu or a progress bar border.

// 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. 调试和原型设计​

¥ Debugging and Prototyping

  • 使用像素完美的线条来调试布局、碰撞盒或网格。由于线条不会缩放，因此它们在开发过程中提供了一致的参考点。

    ¥Use pixel-perfect lines to debug layouts, collision boxes, or grids. Since the lines don’t scale, they offer a consistent reference point during development.

  • 示例：在基于物理的游戏中显示碰撞边界。

    ¥Example: Displaying collision boundaries in a physics-based game.


// 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 必须确定线条的粗细，并创建一个看起来像线但实际上由三角形组成的形状。

    ¥Simpler Drawing Process: Regular lines in PixiJS (when pixelLine is false) need extra steps to be drawn. PixiJS has to figure out the thickness of the line and create a shape that looks like a line but is actually made up of triangles.

  2. 直接线条绘制：使用 pixelLine 时，我们可以告诉显卡 "只需从点 A 到点 B 画一条线"，它知道该怎么做。这比创建和填充形状更简单、更快捷。

    ¥Direct Line Drawing: When using pixelLine, we can tell the graphics card "just draw a line from point A to point B" and it knows exactly what to do. This is much simpler and faster than creating and filling shapes.

可以将其想象成在纸上画一条线 - 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. 厚度为 1px，就是这样！​

¥ Its 1px thick, thats it!

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

    ¥The line is always 1px thick, there is no way to change this as its using the GPU to draw the line.

2. 硬件渲染可能不同​

¥ Hardware may render differently

  • 由于处理线光栅化的方式不同，不同的 GPU 和图形硬件渲染线的方式可能略有不同。例如，某些 GPU 可能会略微不同地定位线条或应用不同的抗锯齿技术。这是 GPU 线渲染的固有限制，超出了 PixiJS 的控制范围。

    ¥Different GPUs and graphics hardware may render the line slightly differently due to variations in how they handle line rasterization. For example, some GPUs may position the line slightly differently or apply different anti-aliasing techniques. This is an inherent limitation of GPU line rendering and is beyond PixiJS's control.

4. 缩放行为​

¥ Scaling Behavior

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

    ¥While the line thickness remains constant, other properties (e.g., position or start/end points) are still affected by scaling. This can sometimes create unexpected results if combined with other scaled objects. This is a feature not a bug :)

示例：具有像素完美描边的框​

¥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

  • 你想要一条不是 1px 粗的线：不要使用 pixelLine。

    ¥You want a line that is not 1px thick: Don't use pixelLine.

  • 你希望线条缩放：不要使用 pixelLine

    ¥You want the line to scale: Don't use pixelLine

结论​

¥Conclusion

对于希望创建在转换下保持一致的清晰、像素完美的线条的开发者来说，PixiJS 工具箱中的 pixelLine 属性非常有用。通过了解它的优势和局限性，你可以将其合并到你的项目中，以在视觉和功能元素中获得干净、专业的结果。

¥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.

查看 线条样式示例代码 以了解 pixelLine 的实际效果！

¥Check out the line styling example code to see pixelLine in action!