Masking a circle: anyone have an example of using drawErase?

Hi Coders, can drawErase be used to “black out” (turn off pixels) in a background? I am thinking about a night-time level, where you only see the immediate area around your ship, everything else is blacked out, like you are in a cave with a torch. I have tried black circle on white background, white circle on black background, and using the various masking modes. I sort of hoped drawErase is what I was looking for.

Any good advice?

Thank you.


Here’s what I a mean:

Some more details of what it is you’re actually trying to achieve would be useful, lest this turn into an X-Y problem.

Depending on what your goal is, you might be better off using a mask with one of the mask drawing functions instead, or there might be a specific way to use drawErase that will give better results.

That said, if your background is pure black then yes drawErase should be capable of achieving the effect you want using image 2 in your diagram.

Here’s a demonstration:
DrawEraseDemo.hex (25.0 KB)

And the source code:

Using the images taken from your image:

CircleFilter LetterM

(It’s just occurred to me that I should have erased the ‘2’, but that’s not a big deal.)

Thank you @Pharap. Whenever I ask a question, and you answer, I am reminded that I should recalibrate before asking a question, in effect “try harder to ask in intelligent question.”

I see what you did, and of course it works great, but what if my “M” was not a sprite, but just some other background graphics, such as the highly technical diagonal line: arduboy.drawLine(0, 0, 127, 63, 1);
Can arbitrary graphics such as that be masked as well?
Thank you.

1 Like

Question: Is the ultimate goal to have a large (possibly the entire screen) background that normally appears as all black, except for a small circle or other object where the actual white areas of the background appear where this object passes/pans over it?

1 Like

Thanks @MLXXXp, the goal is to have a circle of visible pixels (arbitrary main sprite + background drawn objects, anything within the circle) as if it were illuminated and the rest of the screen completely dark, masked to black as it were. So in a scrolling game it would appear as if only the circular area was illuminated and the rest was just black (unlit pixels). Think of tha arcade classic “1942” with a circle of visible area around your plane, but the rest of the screen black.

1 Like

Does the “circle” move around the screen, or is the circle in a fixed position and the “background” pans under it (or both can move)?

1 Like

The circle is in a fixed position in this case, with the BG panning around.

1 Like

It’s less about asking ‘intelligent’ questions and more about being forthcoming about what you’re actually trying to achieve.

There’s a habit among programmers (mainly less experienced programmers, though not always, or programmers who aren’t as into the spirit of open source) of being a bit secretive about what they’re working on, so rather than laying bare what they actually want to achieve they only provide information about their chosen solution (i.e. the X-Y problem) or focus on hypotheticals.

But you’re certainly right in the sense that it’s a habit that can sometimes take a bit of conscious effort to avoid.

I was half way through answering this when you added the information about your intent.

Yes, regardless of what was drawn onto the screen beforehand, when drawing that image over top with drawErase where the circle is black and the rest is white the result will be the kind of ‘porthole’ effect where everything outside the circle is erased to black.

I’m sure I’ve seen this trick on various Mario and Zelda games.

Here’s an example from The Minish Cap:

The video should start at 4:10 if the link is working properly.
Outside the forest it’s actually partly transparent but inside the forest it goes properly black.

That makes matters even easier - you can just run with what’s already been demonstrated.

If the circle needed to move around life would be a bit more difficult.
(You’d need either A) a very large image, or B) a custom function that effectively does the opposite of drawErase.)

1 Like

@Pharap Ah, OK. Not secretive, just a shite programmist. I am surprised about the trend you mentioned, open source seems to be the True Way.

Yes the youtube link worked, indeed that is what I was going for. I had seen it in some games with cave levels.

I was stuck, being too focused on the “Sprite” aspect of drawErase in the docs(not a criticism), yes I see it can erase other pixels as well.

Now to continue my cave game…

Thanks as always.


It depends what your objectives are.

If your objectives are to provide a tool for education, to ensure that a program lives on or to let others use your code with minimal restrictions and without having to pay then open source is indeed a very good tool.

If your objective is profit then open source is much less effective than closed source because you more or less have to rely on alternative models like donations or subscriptions.

(And if your objective is to stop people reverse engineering your code, neither model is particularly effective. :P)

Remember that a sprite (or ‘image’, or ‘bitmap’) is effectively just a 2D grid of pixels.

I must admit, it’s a lot easier to understand the process with images than with ASCII art.


But even then, I think perhaps you need an example of a mixed-colour background to properly understand it:

Feel free to ask for more help and/or advice if you should need it.

1 Like

@Pharap, ah, the pictures do help. Many thanks for your continued help.


1 Like