Skip to content
P4 Software P4 Software / BarcoderX English

Add these docs to Claude

Ask Claude questions about these docs. Claude reads the published pages and links you back to them. Copy this address:

https://p4-software.opendocs.page/mcp

In claude.ai or Claude Desktop: open Settings, then Connectors, choose Add custom connector and paste the address.

In Claude Code, run:

claude mcp add --transport http docs https://p4-software.opendocs.page/mcp

Drawing shapes

Drawing shapes

Applies to: BarcoderX Basic and Ultimate

Status: Built, not yet released. The drawing engine exists and is tested. It is a library inside the engine that is still being built. There is no released package, there is no public interface that you can call to draw directly, and the licensed engine will be the only public way to produce output. The engine can fill shapes, draw outlines, blend colors, clip and run a list of drawing steps on three kinds of surface. It cannot yet draw dashed lines or place pictures. This page says what it does today and what comes later.

BarcoderX draws labels with its own drawing engine. It does not use the drawing functions of the operating system, so a label looks the same on Windows x64, Linux x64 and Linux arm64. Everything on a label, such as text, barcodes and boxes, is drawn with the parts described here. This page describes them as far as a developer needs to know. For a label, the engine works out the drawing from the template, so you will not call these parts yourself.

Shapes

A shape is a path: a series of moves, straight lines and curves. A path can hold several separate pieces, and each piece can be open or closed. A path is built from these steps:

  • A move to a point, and a straight line to a point.
  • A smooth curve with one control point, and a smooth curve with two control points.
  • Closing the current piece.

Four ready-made shapes save the steps: a rectangle, a rectangle with rounded corners (each corner has its own horizontal and vertical radius), an ellipse and an arc of an ellipse.

Moving, scaling and turning

A transform places a shape on the page. A shape can be shifted, scaled by different amounts across and down, and turned by any angle, around the origin or around a point you choose. Transforms combine in the order you give, and a transform that can be undone has an inverse. Turning by an angle that is not a multiple of 90 degrees is drawn directly, and the result is smooth.

Filling a shape

Filling works out which pixels the inside of a shape covers, and by how much. Two rules decide what is inside when a path crosses itself or holds a piece inside another piece:

  • Non-zero. A point is inside if the path winds around it at all. A piece drawn inside another piece in the same direction stays filled.
  • Even-odd. A point is inside if a line from it to the outside crosses the path an odd number of times. A piece drawn inside another piece makes a hole.

The edges are smooth. For every pixel, the engine works out how much of the pixel the shape covers, as a number from 0 (none) to 255 (all). Putting a color on a surface in that proportion is blending (see below). A pixel that the shape covers completely is exactly 255, and one that it does not touch is exactly 0. A rectangle whose edges lie on pixel boundaries is therefore filled with no soft edge at all.

Outlines

The outline of a path is drawn by stroking it. A stroke has:

  • The width of the line.
  • The corners: sharp, rounded or cut off.
  • The ends of the line: flat, rounded or square.
  • A limit for sharp corners. A very sharp corner would make a long spike, so past the limit it is cut off.

Lines and the outlines of boxes and ellipses are drawn this way. Curves are cut into short straight pieces first, as for a fill. Dashed lines are not built yet.

Blending

Drawing with partial transparency puts the new color over what is already there, in proportion to its opacity and to how much of the pixel it covers. Gray surfaces use a fixed weighting of red, green and blue to turn a color into a gray value.

Clipping

A clip area limits where drawing can reach. It can be a rectangle or a path. Clip areas can be nested, up to 64 at the same time. A drawing that nests more, or whose clip shapes would need too much memory, stops at that point with the code BX3006. Where a clip shape and the edge of another shape cross the same pixel, the result is approximate. A rectangle drawn inside a rectangle clip is exact.

Surfaces

A surface is the grid of pixels that you draw on. Three kinds exist:

SurfaceWhat it holds
Color with transparencyRed, green, blue and opacity for each pixel, 8 bits each.
GrayOne 8-bit value for each pixel.
Black and whiteOne bit for each pixel, eight to a byte.

A new surface starts empty: transparent for color and black for gray.

On a black-and-white surface, nothing is ever gray or smoothed. A shape turns a dot black where it covers at least half of the dot. White paint clears dots. Bars drawn as rectangles on whole dots are exact. A thin line that is centered on a whole dot can come out one dot wider than you expect, because exactly half coverage counts as black. A line centered on half a dot, or drawn as a rectangle, keeps its width.

A list of drawing steps

Instead of drawing at once, the engine records the steps in a list: fill a path, fill rectangles, stroke a path, start a clip area (a rectangle or a path) and end it. The list can be written out as plain text in one fixed form, so two lists can be compared exactly. Running a list draws it on a surface. If a step fails, the run stops at that step, says which step it was, and keeps what was drawn before it.

Precision

  • Points are moved onto a grid of 1/4096 of a pixel before the fill, and the fill then uses whole-number arithmetic only. That is why the result does not depend on the processor.
  • Curves are cut into short straight pieces that stay within 0.1 of a pixel of the true curve.
  • In BarcoderX's automatic tests, test labels, drawn with fills and outlines, have the same fingerprint on Windows x64, Linux x64 and Linux arm64.
  • A rectangle whose edges lie on pixel boundaries is exact. A shape with slanted edges is within 0.6 of one step (out of 255) of the exact coverage.
  • Where several overlapping pieces of a path cross the same pixel, their coverage is added up rather than combined, so the result can be far from the true covered area. For overlapping or retracing parts of an outline, an edge pixel can come out much too dark: as measured in the security review, a line drawn out and back over itself gave 255 at a half-covered edge pixel, where 128 is exact. One piece on its own, and pieces that only touch, are exact to within the rounding of the grid.

Limits

BarcoderX checks every limit before it allocates the memory it protects. A drawing that is too large or too complex is refused with a diagnostic code from 3001 to 3006. See Diagnostic codes.

LimitValue
Pixels in one surface, window or coverage area64,000,000 (64 million)
Longest side of a surface, window or coverage area262,144 pixels. This is a fixed property of the design and cannot be raised.
Steps in one path1,000,000
Straight pieces that the curves of one fill are cut into4,000,000
Work for one fill, one outline or one run of a list100,000,000 units. Depending on the work, that is between about 2 and about 8 seconds on a recent desktop processor.
Size of a coordinate after the transformAbout one billion pixels (2 to the power 30)
Clip areas open at the same time64. The memory kept for clip shapes never goes above the pixel limit of a surface.
Steps in the outline of one stroke500,000
Steps in the outlines of all the strokes of one list2,000,000

The limits on straight pieces and on work, and the last three limits, are first choices that the builders made. They have not been confirmed yet and can change before the first release. A host can lower the limits.

The drawing code checks for cancellation at every row and at every 1,024 pieces, so the program that calls it can enforce its own time limit, such as 2 seconds for one label. A coordinate that is not a number, or is too large, is refused.

What is not built yet

  • Dashed lines.
  • Pictures. Placing a picture on a surface, with scaling.
  • Reading a list back from its text form.
  • A label from a template to a printer. Layout, text, shapes and barcodes come together in the label engine, which makes the list of drawing steps of a label. See The label engine. The PNG renderer draws that list and saves a PNG file, and the label service runs both: see PNG output and The label service. The engine is joined to the ZPL writer, which sends the whole label as one picture: see ZPL output. The list of drawing steps stays inside BarcoderX, and a program cannot draw it itself. Text is laid out as described in Text on a label, and it reaches the surface as filled shapes.

BarcoderX is a product of P4 Software.

Was this page helpful?