DUGL Documentation

DUGL : Documentation

Home Graphics Sound Keyboard Mouse Timer
IPX Network GUI

I - Graphics

1/ Coordinate system and limits

* DUGL for all the possible use of a coordinate system ( like : Drawing, defining Views, InViews, Textures position..) the X axis goes always from left to right and Y axis goes always from down to up (ascendent).
* For all possible use of a coordinate system, except for defining a View or an InView, Coordinates X and Y are always relative to the Screen (called Surf later) Origin.
* DUGL use always 32bits signed integers. 11 bits are reserved for point fixed computing, so any adressing on the system coordinate shouldn't exceed the 21 bits (about -16milions and +16milons).
* The Max vertical resolution of a screen used for drawing purpose is set to 2048 pixels.(DUGL 1.0)

2/ Structures

ModeInfo
Store information about a VESA graphic mode.

typedef struct
{
int ResHz; // horizontal resolution
int ResVt; // vertical resolution
int rlfb; // physical adress of the frame buffer
short Mode; // mode ID
short ModeFlag; // mode FLAG capabilities
// to test with the following consts : VMODE_SUPPORTED, VMODE_TTY, VMODE_COLOR, VMODE_GRAPHIC, VMODE_VGA, VMODE_VGAW, VMODE_LFB
char BitPixel; // bits per pixel
char VtFreq,resv; // vertical frequencies or number of screen refresh per sec
} ModeInfo;

Surf
A Surf is where we can draw graphics or where we can store textures, sprites..
It can refer a video or a memory.

typedef struct
{
int vlfb; // used internally to change the origin of the Surf
int ResH, ResV; // horizontal and vertical resolution
int MaxX, MaxY, MinX, MinY; // Upper right Corner and lower left corner relative to to the origin of the surf, of the rect where graphics will take effect, the rest will be clipped
int OrgY, OrgX; // Store value of the origin of the surf, relatively to the left corner
int SizeSurf; // size of the Surf in bytes
int OffVMem; // used internally in case of a video memory
int rlfb; // physical adress of the frame buffer
int RMaxX, RMaxY, RMinX, RMinY; // define drawing rect, but relatively to the lower left corner
int BitsPixel; // bits per pixel of this surf (DUGL 1.01+)
int Resv0,Resv1,Resv2; // reserved (DUGL 1.01+)
} Surf;

View
View is a parameter structure to apply a view inside a Surf.
View is composed from two parts, origine of the surf and clipping area defined by max and min of x and y values.

typedef struct
{
int OrgX, OrgY; // wanted x and origin of the surface
int MaxX, MaxY, MinX, MinY; // clipping area or wanted x,y min and max depending on the kind of the view applied
} View;

3/ Global variables

Surf *VSurf
Pointer to table of video memory Surf.
This table is filled after a InitVesaMode call, and the number of elements is passed as a parameter.
The global var NbVSurf contains the number of element of this table.

ModeInfo *TbMode
Pointer to table of the available 8 bits video mode on this graphic card.

ModeInfo CurMode
current graphic mode.

int CurModeVtFreq
Vertical frequencies of the current graphic mode.

int NbVSurf
Contains the number of video memory Surf.

int NbMode
Contains the number of available video mode.

unsigned int SizeVMem
Available video memory in Bytes.

unsigned int VesaHiVers,VesaLoVers
VESA Bios Low and High version.

Surf CurSurf
The surf where all drawing will be done. could be video or memory surf.

int CurViewVSurf
Index of the currently visible video Surf.

unsigned char TbDegCol[256*64]
A Light lookup table for each color from black to white.
Could be builded automatically calling BuildTbDegCol or PrBuildTbDegCol.

void *PtrTbColConv
A Pointer to lookup table of 256 bytes, giving the color drawn for each color.
Used on the poly kind POLY_EFF_COLCONV.

4/ Graphic functions

int DetectCPUID();
Detect if the processor instruction CPUID could be called in this computer.
Used internally by the function InitVesa.

void ExecCPUID(unsigned int VEAX,unsigned int *PEAX, unsigned int *PEBX, unsigned int *PECX,unsigned int *PEDX);
Execute a CPUID and return results.
Used internally by the function InitVesa.

int DetectMMX();
Return 1 if MMX technolgie is available on this computer, 0 otherwise.
Used internally by the function InitVesa.

int InitVesa();
Must be called, before any other call to a graphic function.
it detects if at least a VESA 2.0 is available and if MMX technologie is available. If detection fail will return 0.
Then it will build a table of the available 8 bits video modes, and Enable MTRR if it's availble and running at a ring 0.

void CloseVesa();
Free all the allocated ressources, by initVesa.
No graphics funtion call, after calling this function.

int InitVesaMode(int ResHz, int ResVt, char BitPixel,int NbVPage);
Init if available a selected video mode with NbVPage video memory.
int ResHz: needed horizontal resolution
int ResVt: needed vertical resolution
char BitPixel : only 8 bits per pixel is supported by now
int NbVPage : Number of wanted Video memory Surf or pages. the call will fails if there is not enough Video memory.
return 1 if sucess and 0 if it fails.

void TextMode();
Init the default bios texte mode.

int SetSurf(Surf *S);
Set the "Surf" where all the drawing function will take effect after a call to this function;
This function do not verify the validity of this "Surf" except for Surf.ResV that should not exceed a max value, 2048 by now for DUGL 1.0.
This function copy the contenent of "Surf *S", so any change made to this structure after a call to SetSurf will not take effect.
return 1 if sucess and 0 if it fails.

int GetMaxResVSetSurf();
Get the max value of Surf.ResV of a "Surf" that we wish to use for drawing.

void GetSurf(Surf *S);
Get a copy of the current active "Surf" for drawing.
The current active sur is also accesible through the global var "Surf CurSurf".

void SetOrgSurf(Surf *S,int LOrgX,int LOrgY);
Set the coordinate origine of a "Surf *S" which is by default set to the left, low corner.

void SetOrgVSurf(int OrgX,int OrgY);
Set the coordinate origine of a all video memory "Surf" which is by default set to the left, low corner.

void WaitRetrace();
Wait until the next vertical retrace happen.
Note : not all SVGA cards provide a compatible VGA registers. in this case it's recommended to use ViewSurfWaitVR(currentVSurfIndex);

void (*SetPalette)(int Dbcol, int Nbcol, void *BGRA);
Alter the current colors palette.
DbCol : index of first color to alter
NbCol : number of palette color to alter starting from DbCol
BGRA : a four bytes table, where each case contain (blue:byte, gree:byte, red:byte, alpha:byte) of the palette color to alter.

void (*ViewSurf)(int NbSurf);
Make immediately the video memory surf number "NbSurf" visible.

void (*ViewSurfWaitVR)(int NbSurf);
Make, when the next vertical retrace happen, the video memory surf number "NbSurf" visible.

DUGL views
We have 4 kinds of views that could be applied to a surf :
- View : the View OrgX and OrgY will be applied to the Surf, and clipping area will coordinates will be applied to the Surf relatively to the left, bottom point of the screen.
- RView : the View OrgX and OrgY will be applied to the Surf, and clipping area will coordinates will be applied to the Surf relatively to the new Orgine of the surf.
- InView : do same as View but x and y limits are clipped inside the current Surf limits.
- InRView : do same as RView but x and y limits are clipped inside the current Surf limits.
example for a screen 640x480
full screen View will be (OrgX=320, OrgY=240, MaxX=639, MaY=479, MinX=0, MinY=0)
full screen RView will be (OrgX=320, OrgY=240, MaxX=319, MaY=239, MinX=-320, MinY=-240)
or
full screen View will be (OrgX=0, OrgY=0, MaxX=639, MaY=479, MinX=0, MinY=0)
full screen RView will be (OrgX=0, OrgY=0, MaxX=639, MaY=479, MinX=0, MinY=0)

void SetSurfView(Surf *S, View *V); :Apply a View to a Surf
void SetSurfRView(Surf *S, View *V); :Apply a RView to a Surf
void SetSurfInView(Surf *S, View *V); :Apply an InView to a Surf
void SetSurfInRView(Surf *S, View *V); :Apply an InRView to a Surf
void GetSurfView(Surf *S, View *V); :Get the the Surf View
void GetSurfRView(Surf *S, View *V); :Get the the Surf View
void SetVView(View *V); :Apply a View to a all current video memory Surf
void SetVRView(View *V); :Apply a RView to a all current video memory Surf
void SetVInView(View *V); :Apply an InView to a all current video memory Surf
void SetVInRView(View *V); :Apply an InRView to a all current video memory Surf

int CreateSurf(Surf *S, int ResHz, int ResVt, char BitPixel);
Fill the Surf pointed by (*S) by a valid memory Surf with ResHz as horizontal resolution and ResVt as vertical resolution. Only the value 8 is accepted for BitPixel.
return 1 if sucess and 0 if it fails.

void DestroySurf(Surf *S);
Free memory ressources used by a surf created by the function CreateSurf(..)

int CreateSurfBuff(Surf *S, int ResHz, int ResVt, char BitPixel,void *Buff);
Do same as CreateSurf, but instead of allocating the buffer it self, it uses the pointer Buff.
return 1 if sucess and 0 if it fails.

void DestroySurfBuff(Surf *S);
Make the surf pointed by (*S) invalid without freeing the buffer used to create this surf.

Colors management

int FindCol(int DebCol,int FinCol,int B,int G,int R,void *PalBGR1024);
Find the nearest color to the color given as (B,G,R) inside the 256 colors palette (B,G,R,A) pointed by PalBGR1024 and starting the search from the color index DebCol and ending at the search at the color index FinCol.
return the index of the nearest color.

int PrFindCol(int DebCol,int FinCol, int B,int G,int R,void *PalBGR1024,float PropBonus);
Find the nearest proportion color to the color given as (B,G,R) inside the 256 colors palette (B,G,R,A) pointed by PalBGR1024 and starting the search from the color index DebCol and ending at the search at the color index FinCol.
An example of color proportion is : for a (B,G,R) (100,8,50) we have => (B > G, B > R, G < R)
So when searching for the best color each color having the same proportion will see his distance between the target distance multiplied by propBonus which varie from 1.0 to 0.0+
return the index of the nearest proportion color.

void BuildTbDegCol(void *PalBGR1024);
Build for each color a light table of 64 cases using FindCol.
For each color the light table will be like :
index 0 : black, index 1 to 31 : nearest colors from black+ to our color, index 32 to 62 our color to white-, index 63 white

Note : this function ignore the color index 0 because it's used as mask color when drawing sprites or masked textures polygones

void PrBuildTbDegCol(void *PalBGR1024,float PropBonus);
Build for each color a light table of 64 cases using PrFindCol with the arg PropBonus.
For each color the light table will be like :
index 0 : black, index 1 to 31 : nearest prop colors from black+ to our color, index 32 to 62 : our color to white-, index 63 white

Note : this function ignore the color index 0 because it's used as mask color when drawing sprites or masked textures polygones

Sprites

void PutSurf(Surf *S,int X,int Y,int PType);
Draw the Surf pointed by (*S) into the current Surf putting the origin of (*S) into the position (X,Y).
We have three constant used to specify the blit kind :
#define NORM_PUT 0
#define INV_HZ_PUT 1
#define INV_VT_PUT 2
This give us four kind of surf blitting :
NORM_PUT : draw or put the surf as it.
INV_HZ_PUT : draw the surf horizontally reversed relatively to the X origin.
INV_VT_PUT : draw the surf vertically reversed relatively to the Y origin.
INV_HZ_PUT|INV_VT_PUT : draw the surf horizontally and vertically reversed relatively to the X origin and Y origin.

void PutMaskSurf(Surf *S,int X,int Y,int PType);
Do same as PutSurf except that it does not draw pixels with value 0. It means that the color index 0 is always the mask color.

int InPutSurf(Surf *S,int X,int Y,int PType,int XIn,int YIn);
Detect if the screen point of coordinate (XIn, YIn) are inside the drawn Surf.
Return 0 if not inside, not 0 otherwise.

int InPutMaskSurf(Surf *S,int X,int Y,int PType,int XIn,int YIn);
Detect if the screen point of coordinate (XIn, YIn) are inside the drawn Masked Surf.
Return 0 if not inside, not 0 otherwise.

int RViewInPutSurf(View *V,Surf *S,int X,int Y,int PType,int XIn,int YIn);
Detect if the screen point of RView coordinate (XIn, YIn) are inside the drawn Surf.
Return 0 if not inside, not 0 otherwise.
note : RView coordinate mean relative to the target Surf origin

int RViewInPutMaskSurf(View *V,Surf *S,int X,int Y,int PType,int XIn,int YIn);
Detect if the screen point of RView coordinate (XIn, YIn) are inside the drawn Masked Surf.
Return 0 if not inside, not 0 otherwise.

int CollisPutSurf(Surf *S1,int XS1,int YS1,int PTypeS1,Surf *S2,int XS2,int YS2,int PTypeS2);
Detect if S1 and S2 collide when drawn to the target Surf.
Return 0 if not collide, not 0 otherwise.

int RViewCollisPutSurf(View *V,Surf *S1,int XS1,int YS1,int PTypeS1,Surf *S2,int XS2,int YS2,int PTypeS2);
Return 0 if not collide, not 0 otherwise.

Drawing

void Clear(int clrcol);
Clear all the current Surf with clrcol without taking care of the clipping area.

void ClearSurf(int clrcol);
Clear the current View with clrcol.

void PutPixel(void *Point,int col);
Draw a pixel into the current Surf without taking care of the clipping area or the size of the Surf.
Point is a pointer to a two 32bits integers table.
We can use :
int Pt[2]; Point[0]=X; Point[1]=y; // or
typedef struct { int x, y } Point; Point pt; pt.x = x; pt.y = y;

int GetPixel(void *Point);
Get the index of the color in the position x and y given by "*Point".

void Line(void *Point1,void *Point2,int col);
Draw a line from the Point1 to the Point2 with the color col.
It take care of the clipping area when drawing.

void LineMap(void *Point1,void *Point2,int col,unsigned int Map);
Draw a line from the Point1 to the Point2 with the color col.
Only the points with a corresponding bit 1 into the "Map" are drawn.
the Map value 0x0000ffff will draw 16 pixels and stop drawing for 16 pixels until reaching Point2.
It take care of the clipping area when drawing.

void Bar(void *Pt1,void *Pt2,int bcol);
draw a filled bar with the color bcol.

void Poly(void *ListPt, Surf *SS, unsigned int TypePoly, int ColPoly);
Draw a convex (without doing the verification) polygon using the "*SS" texture if needed with the FLAG "TypePoly" and using the color ColPoly if needed.
constant used with TypePoly :
- POLY_SOLID : draw a solid polygon filled with ColPoly
- POLY_TEXT : draw a textured polygon
- POLY_MASK_TEXT : draw a color mask 0 textured polygone
- POLY_FLAT_DEG : draw a flat enlighted solid polygone using the first point light value
- POLY_DEG : draw a gouroud enlighted polygone using each light value on each point
- POLY_FLAT_DEG_TEXT : draw a flat enlighted textured polygone using the first point light
- POLY_MASK_FLAT_DEG_TEXT : draw a flat enlighted 0 masked textured polygone using the first point light
- POLY_DEG_TEXT : draw a gouroud enlighted textured polygone using each light value on each point
- POLY_MASK_DEG_TEXT : draw a gouroud enlighted 0 masked textured polygone using each light value on each point
- POLY_EFF_FLAT_DEG : flat enlighten each pixel under the polygone using the first point light value
- POLY_EFF_DEG : gouroud enlighten each pixel under the polygone
- POLY_EFF_COLCONV : use the global 256 bytes lookup table "void*PtrTbColConv" to convert each pixel under the polugone to it's correspondant on the lookup table
- POLY_FLAG_DBL_SIDED : used to draw a double sided polygon

Full poly point structure :
typedef struct {
int x, // pos x
y, // pos y
z; // pos z
int xt, // x inside the texture
yt; // y inside the texture
int light; // 0 to 63 light value : 0 black .. 63 white
} PolyPoint;

structure of ListPt :
typedef struct { int NumberOfPolyPoint; PolyPoint *P1, *P2, ..., *Pn; } ListPoint;
for example :
typedef struct { int NbPt; PolyPt *P1,*P2,*P3,*P4; } QuadPoly;

Provided for convenience.

void line(int X1,int Y1,int X2,int Y2,int LgCol);
Draw a line from (x1,y1) to (x2,y2) with the color LgCol.

void linemap(int X1,int Y1,int X2,int Y2,int LgCol,unsigned int Map);
Draw a mapped line from (x1,y1) to (x2,y2) with the color LgCol.

void putpixel(int X,int Y,int pcol);
Draw a pixel to (X,Y) with the color pcol without caring of the current view.

void cputpixel(int X,int Y,int pcol);
Draw a pixel to (X,Y) with the color pcol taking care of the current view.(slowest)

int getpixel(int X,int Y);
Get the index color of the pixel at (X,Y) without caring of the current view.

int cgetpixel(int X,int Y);
Get the index color of the pixel at (X,Y) taking care of the current view.

void bar(int x1,int y1,int x2,int y2,int bcol);
Draw a filled bar from (x1,y1) to (x2,y2) using the color bcol.

void rect(int x1,int y1,int x2,int y2,int rcol);
Draw a rectangle using the color "bcol" from (x1,y1) to (x2,y2).

void rectmap(int x1,int y1,int x2,int y2,int rcol,unsigned int rmap);
Draw a rectangle using the color "bcol" from (x1,y1) to (x2,y2) where each line is a mapped line using "rmap" as a Map value.