home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 31 / CDASC_31_1996_juillet_aout.iso / vrac / multikit.zip / XMODE.DOC < prev    next >
Text File  |  1996-03-01  |  12KB  |  288 lines
  1.  
  2.  Documentation ─────────────────────────────────────────────────────────────┐
  3.  │                           XMODE Graphics Library                         │
  4.  └───────────────────────────────────────────────────────────── MULTIKIT v1.0
  5.  
  6.  
  7.  
  8.  MULTIKITs' graphics library XMODE.TPU gives you the opportunity to do pro-
  9.  fessional displaying actions on your computers' screen. All you have  ever
  10.  dreamt of comes true with XMODE.TPU: scrolling, palette operations, sprite
  11.  action and more. Easy to handle but very fast though (100% ASM).
  12.  
  13.  
  14.  Global types, constants and variables:
  15.  ──────────────────────────────────────
  16.  The following types, constants and variables are exported. It's not recom-
  17.  mended to change them unless you really do know what your're doing.
  18.  
  19.   Type
  20.    PalType = ^TPalBuf;                palette type
  21.    TPalBuf = Array[0..0] Of Byte;      - pointer to an array of bytes
  22.  
  23.    FntType = Record                   font type
  24.     CharFirst,                         - first char of font
  25.     CharWidth,                         - width of a single char
  26.     CharHeight: Byte;                  - height of a single char
  27.     FontSize:   Word;                  - size in bytes (for loading proc)
  28.     FontAddr:   Pointer;               - memory address
  29.    End;
  30.  
  31.    SprType = Record                   sprite type
  32.     BWidth,                            - width of sprite in bytes
  33.     Height:  Byte;                     - height of sprite in pixels
  34.     Address: Pointer;                  - memory address
  35.    End;
  36.  
  37.   Var
  38.    ActualPage,                        current page for any graphic actions
  39.    VisualPage,                        page which is now visible
  40.    LastPage,                          number of last available page
  41.  
  42.    RetrFlag:               Byte;      reserved for the vsync handler
  43.    RetrFreq,                          vertical retrace frequency (70 Hz)
  44.  
  45.    ActualOffs,                        VRAM offset of the current page
  46.  
  47.    ScrnLogicalPixelWidth,             logical screen width in pixels
  48.    ScrnLogicalByteWidth,              logical screen width in bytes
  49.    ScrnLogicalHeight,                 logical screen height in pixels
  50.  
  51.    PhysicalStartPixelX,               start of physical screen within
  52.    PhysicalStartByteX,                the logical screen (s.a.)
  53.    PhysicalStartY,
  54.  
  55.    MaxScrollX,                        max value for vertical scrolling
  56.    MaxScrollY,                        max value for horizontal scrolling
  57.  
  58.    RightClip,                         clipping rectangle: right border
  59.    LeftClip,                                              left border
  60.    TopClip,                                               top border
  61.    BottomClip:             Word;                          bottom border
  62.  
  63.    ROM8x8_Fnt,                        ROM font 8x8
  64.    ROM8x14_Fnt:            FntType;   ROM font 8x14
  65.  
  66.  
  67.  
  68.  Public procedures and functions
  69.  ───────────────────────────────
  70.  
  71.  General
  72.  -------
  73.  
  74.   Function XInitGraphics(LogicalX, LogicalY: Word): Byte;
  75.             Initialises the graphic system and sets logical screen size  to
  76.             LogicalX x LogicalY. The number of available video pages is re-
  77.             turned or zero if an error occured.
  78.             Due to the limitation of VRAM the size of the virtual screen is
  79.             restricted to 320x800 or 1280x200 or 640x400. You see: LogicalX
  80.             multiplied by LogicalY must be equal or below 256000. The mini-
  81.             mum size is 320x200. LogicalX, the  logical  screen  width,  is
  82.             rounded to the nearest multiple of 8. The  function  calculates
  83.             the number of available video pages and sets up all global  va-
  84.             riables to it's default values. Because the hardware timer must
  85.             be accessed directly in order to calculate the vertical retrace
  86.             frequency you first should init the graphics  system  and  then
  87.             the clock.
  88.  
  89.   Procedure XDoneGraphics;
  90.             This procedure switches your program back to textmode 80x25x16.
  91.  
  92.   Procedure XWaitRetrace;
  93.             Wait until the electronic beam is in the refresh period.
  94.             You can use this procedure to synchronize onscreen graphic  ac-
  95.             tions with the vertical retrace so that your  screen  will  not
  96.             flicker. The function XSETVISUALPAGE and all palette operations
  97.             are already syncronized to the vertical retrace.
  98.  
  99.   Procedure XSetClipRect(X1, Y1, X2, Y2: Word);
  100.             Set the clipping borders.
  101.             You should not access the variables directly but use this  pro-
  102.             cedure instead to set the borders for clipping.
  103.  
  104.   Procedure XSetActualPage(Page: Byte);
  105.             Set the default page for drawing actions.
  106.             If you've more than one video page you can perform drawing  ac-
  107.             tions in the invisible background by using this function. Valid
  108.             values for PAGE are from 0 to LASTPAGE.
  109.  
  110.   Procedure XSetVisualPage(X, Y: Word; Page: Byte);
  111.             Set the visible page and/or scroll over a page.
  112.             X and Y are coordinates containing the start  of  the  physical
  113.             screen within the logical screen. Valid values are from zero to
  114.             MAXSCROLLX or MAXSCROLLY. PAGE is the number of the video  page
  115.             you want to make visible.
  116.  
  117.   Procedure XClearPage;
  118.             Fills the actual video page with color zero.
  119.  
  120.   Procedure XCopyPage(PSrc, PDst: Byte);
  121.             Copies the contents of page PSRC to page PDST.
  122.             This should be used instead of XCOPYRECT because it's much  fa-
  123.             ster when you copy the whole page.
  124.  
  125.   Procedure XShiftRect(X1, Y1, X2, Y2, X, Y: Word);
  126.             Copies the contents of the rectangle X1, Y1, X2, Y2 to  another
  127.             position X, Y on the actual video page.
  128.  
  129.   Procedure XCopyRect(X1,Y1,X2,Y2,X,Y: Word; Src,Dst: Byte; SWi,DWi: Word);
  130.             Copies the contents of the rectangle X1, Y1, X2, Y2 in page SRC
  131.             to the position X, Y in page DST. SWI and DWI are the widths of
  132.             the rectangles within the logical screen.
  133.  
  134.  
  135.  Drawing
  136.  -------
  137.  All drawing functions are operating on the actual video page.
  138.  
  139.   Procedure XPutPixel(X, Y: Word; Color: Byte);
  140.             Set a pixel with color COLOR at position X, Y.
  141.  
  142.   Function  XGetPixel(X, Y: Word): Byte;
  143.             Returns the color of the pixel at position X, Y.
  144.  
  145.   Procedure XLine(X1, Y1, X2, Y2: Word; Color: Byte);
  146.             Draw a line from X1, Y1 to X2, Y2 with color COLOR.
  147.  
  148.   Procedure XRect(X1, Y1, X2, Y2: Word; Color: Byte);
  149.             Draw a filled rectangle with upper left corner X1, Y1 and lower
  150.             right corner X2, Y2 with color COLOR.
  151.  
  152.   Procedure XCircleEmpty(X, Y, Dia: Word; Color: Byte);
  153.             Put an empty circle with upper left corner X, Y onscreen, which
  154.             diameter is DIA pixels and color is COLOR.
  155.  
  156.   Procedure XCircleFilled(X, Y, Dia: Word; Color: Byte);
  157.             Draw a filled circle.
  158.  
  159.   Procedure XTriangle(X1,Y1,X2,Y2,X3,Y3: Integer; Color: Byte);
  160.             Draw a filled triangle.
  161.             This is the only drawing function which allows clipping! It  is
  162.             useful for creating vector objects. You are allowed to use sig-
  163.             ned values for X1,Y1,X2,Y2,X3,Y3 which are the edges of the fi-
  164.             gure.
  165.  
  166.   Procedure XFloodFill(X, Y: Word; Color: Byte);
  167.             Fills an area of pixels which have the same color like the  dot
  168.             at position X, Y with color COLOR starting at X, Y.
  169.  
  170.  
  171.   Palette
  172.   -------
  173.   No palette function will change the contents of the palette  data  array.
  174.  
  175.   Procedure XSetRGB(Color, R, G, B: Byte);
  176.             Set the DAC values of a single color.
  177.  
  178.   Procedure XSetPal(Min, Max: Byte; Var Palette: PalType);
  179.             Set the DAC values given in PALETTE from color MIN to color MAX
  180.  
  181.   Procedure XGetPal(Min, Max: Byte; Var Palette: PalType);
  182.             Read the palette data. PALETTE must be allocated.
  183.  
  184.   Procedure XFadeIn(Min, Max: Byte; Var Palette: PalType);
  185.             Fades the palette from black to the given values.
  186.  
  187.   Procedure XFadeOut(Min, Max: Byte; Var Palette: PalType);
  188.             Fades the palette from the given values to black.
  189.  
  190.   Procedure XBrightIn(Min, Max: Byte; Var Palette: PalType);
  191.             Fade the palette from bright white to the given values.
  192.  
  193.   Procedure XBrightOut(Min, Max: Byte; Var Palette: PalType);
  194.             Fade the palette from the given values to bright white.
  195.  
  196.   Procedure XRotatePal(Min, Max, Disp:Byte; Var Palette:PalType);
  197.             Rotates the palette by factor DISP.
  198.  
  199.   Procedure XMorphPal(Min, Max: Byte; Var SrcPal,DstPal:PalType);
  200.             Morphs SRCPAL palette data into DSTPAL.
  201.  
  202.  
  203.   Font
  204.   ----
  205.  
  206.   Procedure XSetFont(Var Font: FntType);
  207.             Set the default font to FONT.
  208.  
  209.   Procedure XWriteChr(X, Y: Word; Chr: Char; Color: Byte);
  210.             Put a single char CHR at position X, Y in color COLOR onscreen,
  211.             using the current font.
  212.  
  213.   Procedure XWriteStr(X, Y: Word; Str: String; Color: Byte);
  214.             Write an entire string STR at position X, Y in color COLOR.
  215.  
  216.  
  217.  Sprite
  218.  ------
  219.  Because of speed optimization lots of sprite functions are offered to you.
  220.  Speed decreases as follows: XPUTSPRITE (fastest) -XPUTMASKED-XPUTSPRCLIPY-
  221.  XPUTMSKCLIPY-XPUTSPRCLIPX-XPUTMSKCLIPX-XPUTSPRCLIPXY - XPUTMSKCLIPXY (slo-
  222.  west). You're allowed to use signed values. All sprite functions are  per-
  223.  formed on the actual video page.
  224.  
  225.   Function  XSpriteSize(X1, Y1, X2, Y2: Word): Word;
  226.             Returns the required memory for saving a sprite  with  the  ex-
  227.             tends X1,Y1,X2,Y2.
  228.  
  229.   Procedure XPutSprite(X, Y: Word; Var Sprite: SprType);
  230.             Puts a sprite SPRITE at position X,Y onscreen.
  231.  
  232.   Procedure XPutMasked(X, Y: Word; Var Sprite: SprType);
  233.             Puts a masked sprite onscreen. Pixel with color 0 won't appear.
  234.  
  235.   Procedure XPutSprClipX(X, Y: Integer; Var Sprite: SprType);
  236.             Clip a sprite at right or left and put it onscreen.
  237.  
  238.   Procedure XPutSprClipY(X, Y: Integer; Var Sprite: SprType);
  239.             Clip a sprite at top or bottom and put it onscreen.
  240.  
  241.   Procedure XPutSprClipXY(X,Y: Integer; Var Sprite: SprType);
  242.             Clip a sprite at right or left and top or bottom and put it on-
  243.             screen.
  244.  
  245.   Procedure XPutMskClipX(X, Y: Integer; Var Sprite: SprType);
  246.             Clip masked sprite at right or left.
  247.  
  248.   Procedure XPutMskClipY(X, Y: Integer; Var Sprite: SprType);
  249.             Clip masked sprite at top or bottom.
  250.  
  251.   Procedure XPutMskClipXY(X,Y: Integer; Var Sprite: SprType);
  252.             Clip masked sprite at right or left and top or bottom.
  253.  
  254.   Procedure XGetSprite(X1, Y1, X2, Y2: Word; Var Sprite: SprType);
  255.             Read a sprite from VRAM to memory. SPRITE  must  be  allocated.
  256.  
  257.  
  258.  Data i/o
  259.  --------
  260.  These loading functions are designed for loading data files created by the
  261.  MULTIKIT tool programs.
  262.  
  263.   Function  XLoadPal(FName: String; FSeek: LongInt; Var Pal: PalType): Byte;
  264.             Loads a 768 byte palette data file saved by XMDETOOL.
  265.  
  266.   Function  XLoadFnt(FName: String; FSeek: LongInt; Var Fnt: FntType): Byte;
  267.             Loads a font edited with FONTEDIT.
  268.  
  269.   Function  XLoadSpr(FName: String; FSeek: LongInt; Var Spr: SprType): Byte;
  270.             Loads a sprite saved within XMDETOOL. A 8129 byte temporary buf-
  271.             fer is needed to extract the packed data - assure that  it  will
  272.             be available beneath the needed memory for the sprite data.
  273.  
  274.   Procedure XFreePal(Var Pal: PalType);
  275.             Release palette data from memory.
  276.  
  277.   Procedure XFreeFnt(Var Fnt: FntType);
  278.             Release font data from memory.
  279.  
  280.   Procedure XFreeSpr(Var Spr: SprType);
  281.             Release sprite data from memory.
  282.  
  283.  
  284.  
  285.  This unit is part of MULTIKIT. 
  286.  (C) Copyright by TSC-Software, 1995.
  287.  
  288.