this is the fifth section of the {uxn tutorial}! here we introduce the varvara mouse device to explore more possible interactions, and we cover the remaining elements of uxntal and uxn: the return stack, the return mode and the keep mode.
the mouse device in the varvara computer is similar to the controller device in several ways: it has a vector that is called with any mouse event (change of buttons state, movement, scroll movement) and a couple of bytes to check its state.
scrolly will indicate a vertical scroll with a "positive" value when moving upwards (or actually, "away from the user"), and a "negative" value moving downwards (or "towards the user")
it draws our square in the position of the mouse, changing its color when any mouse button is pressed.
=> ./img/screenshot_uxn-draw-with-mouse.png screenshot showing a drawing made with the program: wiggly lines composed of overlapped squares of two different colors
maybe you have noticed that, before today, the mouse pointer has disappeared when entering the uxnemu window.
how could we program and replicate its behavior in uxntal?
we could use a similar strategy to what we did for animating a sprite:
* clear sprite from previous position
* update position
* draw sprite in new position
this procedure can happen whenever the mouse vector is fired.
we can use a set of variables in the zero page in order to store the pointer position, so that we have a way of clearing the sprite in the previous coordinates of the mouse.
note that it draws the pointer in the foreground, and that it uses 'a' in the low nibble of the sprite byte: this implies that it will use color 2 to draw the pointer shape, and will draw with transparency the rest of the tile. (see drawing 1bpp sprites in {uxn tutorial day 2} )
this blending mode would allow you to draw things in the background and have the pointer cover them with its shape only, and not with the whole square tile.
draw some things in the background and see how the pointer looks as it is now. then replace the pointer's sprite byte with e.g. 42 to see the difference!
maybe we could have a JMP to another section of the program, that at its end has another JMP to return to the corresponding position in the on-mouse subroutine?
the jump and stash instruction, JSR, does the same as JMP (unconditionally jump to the address present in the working stack), with the additional action of pushing down into the return stack the absolute address of what would be the next instruction in memory after the JSR.
for example, our jumps could be re-written as follows. in the case of a relative jump:
```
@on-mouse ( -> )
,draw-pointer JSR
( something else here )
BRK
```
## absolute jump
and in the case of an absolute jump:
```
@on-mouse ( -> )
;draw-pointer JSR2
( something else here )
BRK
```
## returning
JSR is pushing the "return address" down into the return stack.
now the question is: how do we take that address from that stack, in order to jump there?
we'd need to use the "return mode"!
# the return mode
similar to the short mode, the return mode in uxn consists in activating a binary flag in the byte that encodes an instruction.
the return mode is encoded in the 7th bit of an instruction byte, counting from right to left.
whenever this flag is set, uxn will perform the given instruction but using as sources the contents of the return stack instead of the contents of the working stack.
in uxntal, we indicate that we want to set this flag adding the letter 'r' to the end of an instruction mnemonic.
as each of the modes is an independent bit, it is possible to combine them, e.g. activating the return mode and the short mode by using the suffix '2r'.
note that the draw-pointer label is accompanied by the stack state notation ( -- ) to indicate that, in this case, it doesn't consume or produce contents from or to the working stack.
also note how this subroutine ends with a JMP2r that indicates that the flow of the program will return to the position after the subroutine was called.
there might be other instances where using "variables" would make more logical and/or readable sense to pass arguments and results.
# stash, don't jump
having introduced the return stack and the return mode, another world of possibilities opens for us: we can also use the return stack as an additional, temporary stack, to store some values while we operate on others.
in order to achieve this, uxn has an instruction called STH, stash.
STH takes a value from the working stack and pushes it down into the return stack.
in return mode, STHr does the opposite: it takes a value from the return stack, and pushes it down into the working stack.
and, as you might have guessed, in short mode this instruction operates moving shorts instead of bytes.
## example: horizontal line
the following is an example subroutine that shows some possibilities of the return stack and mode.
it is a subroutine that draws an horizontal line of a given length (from 1 to 255 pixels, i.e. using one byte), starting from a given x coordinate (short) and using a given y coordinate (short).
these parameters are given as arguments in the working stack.
the subroutine uses the return stack to "stash" one of these arguments while working with the others.
additionally, it has a working loop! written in one of several ways of implementing it :)
the state of both the working (ws) and the return (rs) stacks is shown in the comments after almost every step. the top of the stacks is located at their right.
in order to call the subroutine, you could do something like the following:
```
#0008 ( push initial x )
.Screen/height DEI2 HALF2 ( push y )
#ff ( push length of line )
;draw-horizontal-line JSR2 ( call subroutine )
```
### notes
note that in this specific subroutine, the use of STH2 and STH2r after the &loop sublabel is actually not needed: the operations in between these instructions do touch the working stack but afterwards leave it as it was.
however, it shows how we can use these instructions to have a clean working stack without other values interfering.
### possible exercises
* have the subroutine draw a line made of sprites instead of single pixels
* modify the subroutine so that it can receive as an argument (in the working stack) the color of the sprites or pixels
* modify the subroutine so that it can receive as an argument (in the working stack) the address of the sprite to draw
in uxntal, we indicate that we want to set this flag adding the letter 'k' to the end of an instruction mnemonic.
whenever this flag is set, uxn will perform the given instruction but "keeping" the original values in the corresponding stack.
in other words, in keep mode items will not be consumed from the stack, but the corresponding results will be pushed down into the stack.
keep mode can be combined with the other modes, for a total of eight possible combinations of modes.
## keep mode in arithmetic
we know what the following uxntal code does; it pushes 01 and 02 down into the stack, adds both elements, and pushes the result (03) down into the stack:
```
#01 #02 ( ws: 01 02 )
ADD ( ws: 03 )
```
compare with what happens when using ADDk instead:
```
#01 #02 ( ws: 01 02 )
ADDk ( ws: 01 02 03 )
```
the addition is performed and the result is pushed, but the operands are left in the stack.
it might be hard to think in general of a use for this, but "keep" it in mind!
first of all, let's analyze what's happening with MOD. it is calculating what would be written in infix notation as follows, assumming that the slash (/) indicates an integer division:
if you look carefully, you'll see that DUP2 is there in order to avoid losing the original values in the division, so that we can perform the multiplication and subtraction later.
but now, how can we perform the division without losing its operands and without using DUP2?
with what we have covered already, and in case you want some ideas, here are some things that should be easier to try building now:
## multi-tile sprites
drawing a sprite consisting of several tiles is a process that can benefit from using subroutines: have a subroutine that receives a pair of x,y coordinates in the working stack when called, and use it to draw the tiles in the corresponding positions relative to those coordinates.
## drawing tool
a lot of possibilities here!
maybe start with drawing only when a button is pressed. change color and/or "brush" depending on the button that is pressed.
you can have different selectable "modes": maybe they change the brush you are using, the way the brush behaves (e.g. in mirror? kaleidoscope?), and/or the shapes that are drawn.
keep in mind that you can change a device's vector during runtime: you could have a different on-mouse subroutine depending on the mode you have selected :)
how could you use the mouse wheel as an aid for drawing?
## and more...
basically, the gates for interactive visual applications in the varvara computer are completely open to you now :)
will you create games? small applications, useful or not? an instrument for live visuals? programs targeting specific handheld devices?
some things might appear difficult to build, but fortunately, as of now there's nothing else in the workings of the machine that we haven't covered already.
in {uxn tutorial day 6} we talk about how we can integrate everything that we have covered in order to create even more complex subroutines and programs for the varvara computer.
besides using previous strategies and snippets of code, we cover strategies for drawing and controlling multi-tile sprites, and for checking collisions.