Commodore‎ > ‎BASIC‎ > ‎Keywords‎ > ‎


Keyword Abbreviation Token (hex) Version(s) Classification
PEN P{Shift+E} CE 04 7.0 Function

PEN ( infoType )
Parameters Type Legal Value(s) Note(s)
infoType Integer
  1. VIC-II X axis
  2. VIC-II Y axis
  3. VDC X axis
  4. VDC Y axis
  5. VDC latch flag
Returns Type Value(s) Note(s)
penValue Integer
8 ~ 364 (VIC-II X)
20 ~ 255 (VIC-II Y) 
1 ~ 100 ? (VDC X) 
1 ~ 32 ? (VDC Y) 
0 or 1 (VDC latch)
Return a value about the latched state of a "light pen".
The PEN function is used for "commuicating" with a light pen or light gun..  Similar to the screen and keyboard in that the direction is one-way and you don't need to OPEN a "file" to communicate.  Unlike the screen and keyboard, you can't open a file to a light pen.  One light-pen you may heard about is called Microscribe.
The light pen will only work when plugged into game port 1 (see JOY), and only with a scanning display device, like a CRT monitor (LCD and LED monitors do not use a raster scan do generate their image, so they will fail).  The light pen detects the "bright spot" generated by the CRT while it draws its display raster-by-raster.  When the pen sees this, it sends a signal to the computer which is latched by the video chips.  The light pen may also have one or two buttons, and a sensitivity knob.  The buttons can usually be read with JOY, although the button might enable/disable the light pen (or gun)... such a button would not be directly readable.  In other words, you know it was pressed when a light pen reading actually shows up.
The video chips always know what part of the screen they are drawing (it is their primary task after all).  So when they see the signal from the light pen, they save their current drawing X,Y coordinate in a pair of registers and set a flag in another register.  Thus the user's selected point on the screen has been 'captured'... in theory.  In reality, there is some delay in the generation of the image by the monitor, a delay in the trigger of the light pen itself, and a delay for the video chip to see the light pen's signal.  So the actual latched value will be off a bit from theory.  Software which uses a light pen usually have a calibration option to compensate for the delay.
The line on the game port used to by the light pen as the spot-detected-trigger is the same as used by joystick fire button (mouse left-click).  The line is also used by the keyboard.  So even if you don't have a light pen connected, values can be (falsely) latched by any of those other devices.
The parameter infoType determines what information is returned by PEN.  For the VIC-II (40-column) screen you only use values 0 and 1.  For the VDC (80-column) screen you use values 2 to 4.
For the VIC-II, the latched coordinates are (approximately, see note above) those of the sprites.  That is, inside the visible VIC border you should get an X reading (infoType of 0) between 24 and 344 and a Y reading (infoType of 1) between 50 and 250.  Whenever you read an X or Y value with PEN, that latched value is cleared to zero (the other latched value will be available until you read it, or it is over-written by a new light-pen reading).  The VIC-II never generates a light pen reading of zero for either axis (that would off the visible screen), so if you read a zero, then you know that no value has been latched since you last checked.  In other words there is no VIC-II latch flag like the VDC has.  On the other hand, the VIC screen offers the programmer the option to use COLLISION, which will interrupt your program and call a subroutine when a new light pen value is latched.
For the VDC, the latched coordinate is unfortunately only in terms of character cells, not pixels like the VIC-II.  The X reading (infoType of 2) should be about 1 to 100 and the Y reading (infoType of 3) should be about 1 to 31 (NTSC) or 1 to 37 (PAL).  This assumes you are not using a black background (black does not register well with light pens).  If you are, the range of values would be smaller (inside the border).  Finally the infoType value 4 is given to get the VDC latch value.  Unlike most BASIC logical values (where -1 is true), this function will return +1 if a value has been latched and 0 if not.  BASIC does not clear any VDC register (no matter which infoType you request) so it is not certain how long a latched value remains available... well it will be over-written when a new value is latched and this will naturally set the VDC latch value to "true".
If infoType is omitted or is not a valid expression, SYNTAX ERROR occurs.  If infoType is a string, TYPE MISMATCH ERROR occurs; you can use VAL to make a string numeric.  Otherwise the infoType is converted with INT.  If the result is not a Legal Value (0 to 4) then ILLEGAL QUANTITY ERROR occurs.
 220                  'Sprite X' coordinate... about 200 on bitmap

 8                    'Sprite Y' coordinate... about -40 on bitmap (off screen)

 0                    no VDC coordinate latched

  Compare With  
  Contrast With  
  See Also  

© H2Obsession, 2014