@DATABASE 2D Drawing V1.00
$VER: Pure Basic - 2D Drawing library V1.00 (01.09.1999) © Fantaisie Software
@NODE MAIN "2D Drawing library"

  @{b}Pure Basic - 2D Drawing library V1.00@{ub}

    The 2D drawing is all the 2D rendering operations you can do
    on a visual area. Tracing a line, a box, a circle or even a text
    is condering as a 2D rendering operation. You just have to
    specify the output (screen, window, bitmap..) and draw...

  @{b}Commands summary:@{ub}

    @{" BackColour      " LINK BackColour}
    @{" BoxFill         " LINK BoxFill}
    @{" Circle          " LINK Circle}
    @{" Cls             " LINK Cls}
    @{" CopyBitmap      " LINK CopyBitmap}
    @{" CursX           " LINK CursX}
    @{" CursY           " LINK CursY}
    @{" DrawingFont     " LINK DrawingFont}
    @{" DrawingMode     " LINK DrawingMode}
    @{" DrawingOutput   " LINK DrawingOutput}
    @{" DrawingRastPort " LINK DrawingRastPort}
    @{" Ellipse         " LINK Ellipse}
    @{" FrontColour     " LINK FrontColour}
    @{" Locate          " LINK Locate}
    @{" Line            " LINK Line}
    @{" ObtainBestPen   " LINK ObtainBestPen}
    @{" Plot            " LINK Plot}
    @{" Point           " LINK Point}
    @{" PrintText       " LINK PrintText}
    @{" ReleasePen      " LINK ReleasePen}
    @{" TextLength      " LINK TextLength}
    @{" TextStyle       " LINK TextStyle}

  @{b}Example@{ub}

    @{" 2D Drawing demo " LINK "PureBasic:Examples/Sources/Bitmap&Drawing.pb/Main"}

@ENDNODE

@NODE Plot

    @{b}SYNTAX@{ub}
  Plot(x,y)

    @{b}STATEMENT@{ub}
  Draw a plot in the active color (set by FrontColour()) in the current window.

@ENDNODE


@NODE BoxFill

    @{b}SYNTAX@{ub}
  BoxFill(x1, y1, x2, y2)

    @{b}STATEMENT@{ub}
  Draw a filled box in the active color (set by FrontColour()) in the
  current output.

@ENDNODE


@NODE BackColour

    @{b}SYNTAX@{ub}
  BackColour(Colour)

    @{b}STATEMENT@{ub}
  Set the default background colour for graphic functions and text display.

@ENDNODE


@NODE CursX

    @{b}SYNTAX@{ub}
  Result.w = CursX

    @{b}FUNCTION@{ub}
  Returns the text cursor X position in the current output.

@ENDNODE


@NODE CursY

    @{b}SYNTAX@{ub}
  Result.w = CursY

    @{b}FUNCTION@{ub}
  Returns the text cursor Y position in the current output.

@ENDNODE


@NODE FrontColour

    @{b}SYNTAX@{ub}
  FrontColour(Colour)

    @{b}STATEMENT@{ub}
  Sets the default foreground colour for graphic functions and text display.

@ENDNODE


@NODE Locate

    @{b}SYNTAX@{ub}
  Locate(x,y)

    @{b}FUNCTION@{ub}
  Sets the text cursor to given position (for PrintText()).

@ENDNODE


@NODE PrintText

    @{b}SYNTAX@{ub}
  PrintText(String$)

    @{b}STATEMENT@{ub}
  Display the given string  on  the  used  output  at  position  set  by
  Locate() and with the colours set by FrontColour(). You can use TextStyle()
  to change the output style (bold, italic, underline) and DrawingMode()
  to change the way the text is rendered.

@ENDNODE


@NODE TextStyle

    @{b}SYNTAX@{ub}
  TextStyle(Style)

    @{b}STATEMENT@{ub}
  Set the style for future text output.

  The legal Style values are:

    0 = Nothing
    1 = Underline
    2 = Bold
    4 = Italic

  You can mix these values if needed (Bold+Italic will be 2+4 = 6)

@ENDNODE


@NODE DrawingFont

    @{b}SYNTAX@{ub}
  DrawingFont(FontID)

    @{b}STATEMENT@{ub}
  Sets the current font to given FontID. All new text rendered will
  be done with the new specified font.

  FontID MUST be a legal IntuiFont Pointer. You can use the NFont library
  to load any font and pass the FontID() pointer to this function.

@ENDNODE


@NODE Circle

    @{b}SYNTAX@{ub}
  Circle(x, y, Radius)

    @{b}STATEMENT@{ub}
  Draw an outlined circle at the position x,y with the size of Radius.

@ENDNODE


@NODE Cls

    @{b}SYNTAX@{ub}
  Cls(Colour)

    @{b}STATEMENT@{ub}
  Set the entire output to the given colour.

@ENDNODE


@NODE CopyBitmap

    @{b}SYNTAX@{ub}
  CopyBitMap(BitMapID, SourceX, SourceY, DestX, DestY, Width, Height)

    @{b}STATEMENT@{ub}
  Copy the specified area situated in the given BitMapID, and determined
  by SourceX, SourceY (x,y position in the bitmap to start the copy) and
  Witdh, Height which give the size of the copied data. DestX and DestY
  allow you to copy the data at this position in the current output.

  This function is 100% OS Friendly and clipped.

@ENDNODE


@NODE DrawingOutput

    @{b}SYNTAX@{ub}
  DrawingOutput(RastPort)

    @{b}STATEMENT@{ub}
  Set the drawing output to the specified rastport. After setting this, all
  the Drawing commands are rendered on this rasport. You must specify a
  valid rastport pointer.

    You can use the following functions to easily get rastports from objects:

      + WindowRastPort()
      + ScreenRastPort()
      + BitmapRastPort()

    Example:

    DrawingRastPort WindowRastPort()  ; All drawing will be done on the window.


@ENDNODE


@NODE DrawingMode

    @{b}SYNTAX@{ub}
  DrawingMode(Mode)

    @{b}STATEMENT@{ub}
  Change the drawing mode for graphics output:

    Here is a quick list of valid modes:

      #JAM1       = 0 : For text output, leave the background transparent.
      #JAM2       = 1 : For text output, print text with background colour
      #COMPLEMENT = 2 : XORred graphics
      #INVERSVID  = 4 : Use in conjunction with JAM2, it inverts background
                        and foreground colours when printing text.

  Note: These constants are found in the AmigaOS resident file.

@ENDNODE


@NODE Ellipse

    @{b}SYNTAX@{ub}
  Ellipse(x, y, RadiusX, RadiusY)

    @{b}STATEMENT@{ub}
  Draw an outlined ellipse at the position x,y with size of RadiusX
  and RadiusY.

@ENDNODE


@NODE Line

    @{b}SYNTAX@{ub}
  Line(x1, y1, x2, y2)

    @{b}STATEMENT@{ub}
  Draw a line in the active color (set by FrontColour()) on the current
  output.

@ENDNODE


@NODE Point

    @{b}SYNTAX@{ub}
  Colour.w = Point(x, y)

    @{b}STATEMENT@{ub}
  Return the colour number at the coordinates (x,y) in the current
  output.

@ENDNODE


@NODE TextLength

    @{b}SYNTAX@{ub}
  Length.w = TextLength(x, y)

    @{b}STATEMENT@{ub}
  Return the pixel length of the given string in the current output.
  The main advantage of this function is so you can get the real length
  of any strings used with any fonts (even non-proportional ones).

@ENDNODE


@NODE ObtainBestPen

    @{b}SYNTAX@{ub}
  Result.w = ObtainBestPen(r, g, b, precision)

    @{b}STATEMENT@{ub}
  Return the colour number with the best match to the given parameter.
  On a public screen with free colours, it will allocate a new colour
  with the (r,g,b) value. The precision parameter tells the command
  how it should be detected:

    Valid values of 'precision' (follow by system constante):
      Exact = -1 (#PRECISION_EXACT)
      Image =  0 (#PRECISION_IMAGE)
      Icon  = 16 (#PRECISION_ICON)
      Gui   = 32 (#PRECISION_GUI)

  Note: You MUST use the ReleasePen(Result) for any colours you have allocated
  before quitting your program, else the colours will never be released
  to the free colour bank of the screen (very bad).

@ENDNODE


@NODE ReleasePen

    @{b}SYNTAX@{ub}
  ReleasePen(Pen)

    @{b}STATEMENT@{ub}
  Tell the system than this pen isn't used (locked) by your program, so
  that other programs can use it. You must call this function if you have
  allocated any pens with ObtainBestPen().

@ENDNODE

@NODE DrawingRastPort

    @{b}SYNTAX@{ub}
  *RastPort = DrawingRastPort()

    @{b}STATEMENT@{ub}
  Return the value of the currently used RastPort for output (for
  advanced programmers).

@ENDNODE