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

CIRCLE

Keyword
Abbreviation Token (hex) Version(s) Classification
CIRCLE C{Shift+I} E2 3.5, 7.0 Command and Statement
TRAP T{Shift+R} E2 4.7 Statement

Syntax  
CIRCLE [  colorSource ] [ , { [ + | - ] xVal [ , [ + | - ] yVal ] distance ; angle } [ , [ xRadius ] [ , [ yRadius ] [ , [ startArc ] [ , [ endArc ] [ , [ rotation ] [ , stepAngle ] ] ] ] ] ]
 
Parameters Type Legal Value(s) Default Value Note(s)
colorSource Integer
0 or 1 (high-res)
0 to 3 (multi-color)
1
The actual color on-screen depends
on the colorSource assignment by COLOR
xVal Integer*  -32768 to +32767  pixel cursor X  rectangular X ordinate or offset for center
yVal  Integer*  -32768 to +32767  pixel cursor Y rectangular Y ordinate or offset for center 
distance Integer*  -32768 to +32767  polar distance for center 
angle Unsigned Integer  0 to 65535  undefined polar angle for center
xRadius  Unsigned Integer  0 to 65535  1/2 width of circle 
yRadius Unsigned Integer  0 to 65535  xRadius[*2]  1/2 height of circle; default times 2 for multi-color mode
startArc Unsigned Integer  0 to 65535  in clockwise degrees; should not be more than endAngle
endArc  Unsigned Integer  0 to 65535  360  in clockwise degrees
rotation  Unsigned Integer  0 to 65535  ellipse rotation in clockwise degrees 
stepAngle Unsigned Byte 1 to 255  in degrees 
*Due to a bug in the original C128 ROMs (start-up message says (c)1985), only positive/unsigned values of 0 to 65535 may be used.
 
 
Purpose  
Plot a (partial) ellipse or regular polygon on the bitmap screen.

 
 
Remarks  
All parameters are optional.  Without any, CIRCLE will (slowly) plot a single pixel (actually the same pixel 180 times).
 
The coordinate (after the optional colorSource) defines the center of the "circle"; if not specified, it defaults to the "pixel cursor" (the last point calculated in the previous bitmap command).  A specified coordinate will be effected by SCALE if it is active.  The resulting values may be off-screen, as long as they are legal as shown above.
 
The optional xRadius and yRadius define the size of the "circle".  The width of a complete (and non-rotated) "circle" is defined by two times xRadius (default 0).  The height of a complete (and non-rotated) "circle" is defined by two times yRadius.  The default yRadius depends on the GRAPHIC mode.  For high-resolution, it is the same as xRadius; for multi-color, it is twice the xRadius.  Because the pixels are not square (in either mode), the result will be an ellipse instead of a true circle (assuming all the following parameters use default values).
 
A complete "circle" need not be drawn.  A "partial circle" or arc may be drawn instead.  To do this, specify a startArc and endArc with a difference less than 360 (the length of the arc in degrees).  The endArc should be greater than startArc or you will get strange results!  Either (or both) may be more than 360 degrees, in this case the result is the same as if both values were modified by subtracting startArc - Mod(startArc, 360) from both values.  If that doesn't make sense, then just keep startArc in the range 0 to 359 and endArc in the range 0 to 719 such that endArc >= startArc (and usually endArc-startArc <= 360).  And if that doesn't make sense, you'll just have to play around with it!
 
The rotation will rotate the "circle" by the specified number of degrees.  If you can manage to draw a true circle, this will have no effect (assuming default stepAngle).  In the typical case (an ellipse, not a true circle), the angle is only relevent modulo 180 due to symmetry.  For example a rotation of 45 is effectively the same as a rotation of 225 or 405 (45 + 180*1 or 45 + 180*2).
 
The stepAngle can be used to generate regular polygons instead of an ellipse/circle.  You see, by default, this command really draws a 180-sided polygon!  The number of sides in the polygon equals 360 divided by the stepAngle (so with the default value of 2, you get 360/2 = 180 sides).  Here are values for polygons you may want to try:
  • 120 degrees for a triangle [trigon?] (3 sides)
  • 90 degrees for a parallelogram [tetragon?] (4 sides)
  • 72 degrees for a pentagon (5 sides)
  • 60 degrees for a hexagon (6 sides)
  • 51 degrees for a septagon (7 sides)
  • 45 degrees for an octogon (8 sides)
  • 40 degrees for a nonagon (9 sides)
  • 36 degrees for a decagon (10 sides)
  • 30 degrees for a dodecagon (12 sides)
As you exceed 12 sides, the result looks more and more like a circle (as the stepAngle gets smaller).  If you are not drawing a very large (near full-screen) size circle, using a stepAngle of 10 should give acceptable results (a 36-sided polygon) but render noticebly faster than the default value.
 
The width plotted on screen of each "dot" of all line-segments is controlled by a secret BASIC variable.  That secret variable can be set with WIDTH.  If it is 1, each dot will be 1 pixel wide; if it is 2, each dot will be 2 pixels wide.
 
Strangely in all versions, negative angles are not allowed!  Try adding 360 (or 720) to fix this problem (this works for positive angles too), but see the notes about startArc and endArc.
 
Any floating-point numbers will first be converted to integers (see INT).  If any value is out-of-range (see above) an ILLEGAL QUANTITY ERROR is generated.  If no bitmap has been setup (see GRAPHIC), a NO GRAPHICS AREA is generated.
 
Example of optional colorSource and optional center:
DRAW 1,60,60: CIRCLE , ,, 50 : REM CIRCLE 1, 60,60, 50,50[*2]
 
Example of relative rectangular and polar coordinate:
DRAW 1,60,60: CIRCLE , +10,-10, 40 : REM CIRCLE 1, 70,50, 40,40[*2]

READY.
DRAW 1,60,60: CIRCLE , 20; 30, 40 : REM ~CIRCLE 1, 70,43, 40,40[*2]
 
Example of very wide and very tall ellipse:
CIRCLE 1, 60,60, 100,20 : REM very wide

READY.
CIRCLE 1, 60,60, 20,100 : REM very tall
 
Example of an arc (semi-circle), the "bottom half" of an ellipse:
CIRCLE 1, 60,60, 40,, 90,270 :REM radius 40,40[*2] and arc 90~270 degrees
 
Example of a rotated ellipse:
CIRCLE 1, 60,60, 40,120, ,, 30 :REM radius 40,120 arc 0~360 degrees, rotate 30 degrees
 
Example of polygons:
CIRCLE 1, 60,60, 40,, ,, , 120 :REM triangle with "radius" of 40,40[*2]

READY.
CIRCLE 1, 60,60, 40,, ,, 45, 90 :REM rectangle with "radius" of 40,40 [wrong in multi-color]

READY.
CIRCLE 1, 60,60, 40,, ,, , 90 :REM diamond with "radius" of 40,40[*2]

READY.
CIRCLE 1, 60,60, 40,, ,, , 72 :REM pentagon with "radius" of 40,40[*2]

READY.
CIRCLE 1, 60,60, 40,, ,, , 60 :REM hexagon with "radius" of 40,40[*2]

READY.
 
Compare With  
 
See Also  

© H2Obsession, 2014
Comments