Pxl Library 2.0


nathanielbabiak 2020-11-01 03:40 (Edited)

This upload is just all of the subprograms in one spot. As always, the default code can be used to experiment with different sizes and layouts of windows using the Pxl BG Tool.

To reduce the learning curve, I've updated all my old Pxl Library 1.0 uploads for 2.0 with examples for each of these topics:

Pxl Library 2.0 is Here!


I wrote Pxl Library 2.0 to be as accessible as possible, but it's still pretty complicated. In the source code there's a bunch of global variables defined at the top, then the pxl display initialization, then some ASCII art.

You can delete everything inside the ASCII art and put your code there. To draw a pixel, use PXL2_SETP( PX, PY, PC ), which has arguments of the pixel coordinates (x, y) and pixel color (0 to 3).

For other pxl-level commands, the arguments in each of the subprograms will give you a hint. PX,PY is integer pixel coordinates, FX,FY is floating point pixel coordinates. And to keep it easy, start with the PXL2 subprograms, even though they're slower. (The PXL subprograms require slightly different arguments, boolean values, and it's really annoying to use them.)

Pxl System Initialization

The first few subprograms (lines 35 to 122) are for initialization, just ignore them for now.

Display Commands PXL_CLS and PXL_PALETTE

The (line 123) subprogram PXL_CLS is an extension of the LowRes NX command, and works for both 2 and 4 color pxl display. (The included display is a 4 color pxl display.)

You can call (line 134) PXL_PALETTE( RED, GREEN, BLUE ) only when using a 2 color pxl display, and it'll set the foreground pixel color for you. (The background color of the pxl display will be set to match the system background color.)


Starting on line 140, the PXL drawing subprograms are SET (meaning "set" a pixel to a certain color), TEST (to return a pixel's color), VERT and HORZ (for drawing straight lines), CIRC (for outline circles), CIRCFILL (for filled circles), LINE (which has a pair of X1,Y1 and X2,Y2 arguments for diagonal lines), RECT (for filled rectangles), TRIFAST (a triangle drawing routine that is "fast" because it isn't pixel-perfect), and TESSFAST (a tessellated triangle drawing routine for 3d polys, fast for the same reason).

Note that VERT, HORZ, and RECT require the coordinate arguments to be sorted, i.e., FY1<=FY2 and/or FX1<=FX2 (sorting arguments is not required for LINE, TRIFAST, or TESSFAST).

The suffix CLIP means a drawing command will automatically clip the border of the pxl window.

Also, some subprograms have variations for PX,PY and FX,FY. The PX,PY variants are for (integer) pixel coordinates, whereas the FX,FY variants are for floating-point (non-integer) pixel coordinates. Rounding is built into the FX,FY variants, which will be super useful for 3D polys.


These subprograms are extensions of LowRes NX.

PRINT/TEXT are the basically same, except PRINT is slower, but automatically character-wraps and processes CHR($10) correctly. Don't use CHR($10) with TEXT.

The meaning of MODE depends on whether you're using the 2-color or 4-color variant. For 2-color (PXL_):

For 4-color (PXL2_):

CELL is limited to PX being a multiple of 8, and PY being a multiple of 2, it'll round to these multiples for you.

SPRITE is much slower than CELL, but PX and PY can be any integer.

The meaning of the MODE argument varies depending on whether you're using the 2-color or 4-color variant. For 2-color (PXL_):

For 4-color (PXL2_):

ESCSEQ will process escape sequences in a string. It's not really part of Pxl Library - it works with any LowRes NX string commands. Lowercase encoding is automatic.

Image Commands LOAD and SAVE

These commands grab a whole rectangular section of the screen and put it somewhere in working memory, but it's limited to PX being a multiple of 8 (no limit on PY).

Pxl Library 2.0.nx | Open in app
2020-11-10 06:28
Pxl Library 2.0.nx | Open in app
2020-11-06 21:24
Pxl Library 2.0.nx | Open in app
2020-11-05 22:46
Pxl Library 2.0a.nx | Open in app
2020-11-01 03:40

GAMELEGEND 2020-11-01 04:11

this is just so COOL

nathanielbabiak 2020-11-01 04:18 (Edited)

Oh I forgot to mention... The "default" code between the ascii art is a bit special. It's intended to demonstrate any changes you make if you play around with the Pxl BG Tool (adjusting window specifications and window layout). So if you use the tool and get all the way to the "save" page successfully, you can just save the BG to ROM 3 and the pxl metadata to ROM 4 of *this* upload, then re-run this program. It should show you all the window changes you've made!

Timo 2020-11-01 17:06

Looks very impressive, but I'll stick to sprites and tiles ;)

was8bit 2020-11-05 04:01

Ok, so i have a question... is there a way to READ an existing pixel color?

nathanielbabiak 2020-11-05 04:14

For the 4-color setup, right now you have to use PXL_TESTP twice (once with USE_HI=FALSE, again with TRUE). I'll update tomorrow with PXL2_TESTP, which will just return 0...3

was8bit 2020-11-05 05:34 (Edited)

Sounds cool :)

Thanks much :)

nathanielbabiak 2020-11-05 22:52 (Edited)

I've added PXL2_TESTP. I've also added cell, sprite, text, and print subprograms. And saved a 6x8 font if you want to use that instead of the default 4x6 font, though you'll have to swap the two ROMs that are commented-out.

nathanielbabiak 2020-11-06 00:23 (Edited)

Another thing I forgot to mention... In the old version from late 2019, was8bit asked that the cell and sprite extensions have two special modes ("replace" and "transparent") rather than the numerous boolean arguments (the boolean arguments are crazy complicated). So for this version, the monochrome extensions (prefixed with PXL_) have a simplified set of boolean arguments, and the four-color extensions (prefixed with PXL2_) have just a "mode" argument: mode=2 (replace), and mode=3 (transparent).

Actually, the monochrome extensions also have mode=2 (replace), mode=1 (transparent "or"), and mode=0 (mask "and"), mode=-1 (transparent toggle "xor"), and mode=-2 (negative bitmask then replace).

GAMELEGEND 2020-11-06 00:53 (Edited)


nathanielbabiak 2020-11-06 00:59

Thanks! I'm experimenting with dithering a bit. I'm trying to figure out if 8-scale colors are going to be too slow to include in a 3D polygon system... I think it'll be possible, but probably too slow for fast moving polys.

was8bit 2020-11-06 04:49

Wowzers... gonna take some time to wrap my brain around this cool stuff :D

nathanielbabiak 2020-11-06 21:33 (Edited)

Today's update fixes a bitmask issue effecting HORZ, RECT, CIRC, TRIFAST, and TESSFAST. I'm starting to realize how annoying boolean arguments can be, so I've also added four-color variations of all the monochrome drawing subprograms for simplicity (even though it's twice as slow). The four-color variations are prefixed with PXL2, and take pixel color (PC) as an argument. I've also reordered the arguments of all subprograms for consistency.

There's only a few things left to do! My list is: (1) filled circles, (2) pixel-perfect triangles and polys, and (3) saving and loading pictures. At some point I'll experiment with two more things, but I think it's pretty close to done: (4) experimenting with dithered drawing commands, and (5) experimenting with a SIZE modifier for cells and sprites.

was8bit 2020-11-07 10:48

Super awesome :)

nathanielbabiak 2020-11-10 06:38 (Edited)

This will be the final update, unless I ever come back to pixel-perfect triangles and polys at some point.

Today's upload finishes filled circles and saving and loading pictures. I've determined dithering will be too slow to show dynamic polys, so it's not included either (it'll be in a demo soon of static polys). I also decided SIZE is just gratuitous.

I also reorganized PXL_TEXT and PXL_PRINT (and their PXL2_... variants) to exclude the escape sequence processing. ("Escape sequence processing" is how I'm able to show lowercase letters and double-quotes.) Use ESCSEQ to process any escape sequences (and convert to lower case) prior to passing the string to PXL_TEXT or PXL_PRINT (and their PXL2_... variants).

As a bonus, I've also included a template for custom fonts. Unlike PXL_TEXT and PXL_PRINT (and their PXL2_... variants), which are limited to 8x8 bitmaps, the custom font template in ARIAL8PT works up to 16x16. It checks for any large characters and addresses them accordingly.

was8bit 2020-11-10 07:41

Wowzers... i will explore as time permits... this is wonderful, thanks for making and sharing :)

nathanielbabiak 2020-11-10 17:37

Of course! :-) I'm just happy this is finally finished! I didn't want to make any more progress on the Wolf 3D game until this was done, since so much of this work will be used there.

was8bit 2020-11-11 04:27

Ooo cool game on the horizon :D

Mrlegoboy 2020-11-17 06:03


nathanielbabiak 2020-12-06 21:37 (Edited)

Today's upload fixes a few minor bugs. Please feel free to upload your own Pxl Library creations! But do verify you're using the current version, it's in the source code just below the global declarations: "ED. DECEMBER 6, 2020".

(I've also updated this post's topic to include a manual.)

Mrlegoboy 2020-12-08 01:06

Can you release different, simplified versions of this? Maybe one version tailored towards 3d, and another with just the text commands?

nathanielbabiak 2020-12-08 02:04 (Edited)

I'm sorry it's so big. I had tried to split apart the first version (Pxl Library 1.0). What happened was, folks were confused about what exactly the "library" consisted of, and rightly so, because it wasn't all in one place. (And I had confused things further by writing far too many "helper" subprograms, some of which were required by multiple uploaded topics.)

For this version (Pxl Library 2.0), "all" of the subprograms are completely independent of each other, and my hope is that folks will just copy-over the subprograms they want to use.

There's actually four general exceptions to "all":

To reduce the learning curve, I've updated all my old Pxl Library 1.0 uploads for 2.0 with examples for each of these topics:

(If you have questions on those topics specifically please comment on those uploads to keep the threads clean.)

If there's another topic you'd like me to "demo", please comment here to let me know. I'd be happy to make any specific "demos" you'd like. :-) Nobody will use the library without demos!

P.S. There's no specific subprograms for 3D - just take your 3D coordinates (X,Y,Z) and project to screen coordinates (X/Z,Y/Z), then use the Pxl Library commands to show lines, points, circles, triangles, etc. Regardless, I do plan to update my 3D test upload eventually (

Log in to reply.