═══ 1. Title Page ═══ BGI Graphics Emulator for OS/2 ═══ 2. Introduction ═══ Introduction ───────────────────────────────────────────────────────────────────────────── When Borland created their Borland C++ for OS/2, they did a good job of providing backwards compatibility for DOS text programs, however no provision was made for backwards compatibility with DOS graphics programs. This makes sense, since OS/2 provides a very sophisticated graphics environment. However, for people with an investment in programs using the BGI graphics API, the effort to port to this new environment may not be worthwhile. And for those writing programs which use only simple graphics, the Presentation Manager API can be daunting. This package is addressed to these needs. It aims to allow porting of existing BGI applications to OS/2 with very little modification to the source. It also, by handling some of the more complex Presentation Manager details transparently, allows for a simpler transition from DOS based, procedural programs, to the more sophisticated OS/2 programs. For example, using this emulator, it is relatively trivial to write a program which uses multiple threads to calculate different parts of the graphic image, but still display the image using the familiar BGI graphics commands. How does it work? While the implementation is still not fully defined at this time, the basic operation is as follows. When a program compiled with the BGI emulator starts, it splits into two threads. One thread is the user's code executing. The second thread maintains a window on screen. This second thread handles screen repaints, resizes, and so on, transparently to the user's code. The user's code calls the normal BGI functions, which are translated into Presentation Manager calls. The two threads are synchronized using mutex semaphore's behind the scenes, so that the user's program will never try to modify the current window while it is being repainted for example. The current version (0.5) is essentially a pre-alpha release. It is far from feature complete, and some major parts of the implementation are not even fully defined yet. However, it was thought important to get some early feedback on the development direction (and some early bug reports) to help focus further efforts. Hopefully there will be regular further pre-release versions, until the release version is ready. Please see the section How to Report Problems for information on reporting problems and suggestions. Please carefully read the sections in this document on Supported Features and Future Directions so that you will have some idea of what is working in the current version, and what is planned for future versions. Also, check Functions Currently Supported check out any functions that you are using to make sure they are implemented and to see what restrictions the current implementation has. ═══ 3. Installation ═══ Installation ───────────────────────────────────────────────────────────────────────────── Installation of the package is relatively simple. Currently, it is necessary for you to supply a copy of the include file graphics.h which is supplied with the Borland C compilers for DOS. It contains all of the structures and definitions required to use the BGI package. The legal issues of distributing this file with the package have not yet been explored. You must place graphics.h in the include directory of your BCOS2 installation. The installation procedure has been designed to work with the default directory setup of Borland C++ for OS/2. If you have a different setup, you should create a set of temporary directories with the required structure, and then move the installed files afterwards. To install the package, unzip all of the supplied files into a temporary directory, or place them on a floppy. From within this directory, run the REXX script install.cmd. The syntax is: install is the directory in which BCOS2 is installed. For example: install c:\bcos2 Note: In the rest of this discussion, it will be assumed that the compiler is installed in \bcos2. Substitute the appropriate directory for your installation where required. The install script does two things. First, it copies the file bgi.lib to \bcos2\lib - the default location for the Borland libraries. You can move it from there to another directory if you wish - just make sure that you link it in to your application when compiling. Second, it edits the graphics.h file. It expects to see this file in \bcos2\include. These edits add in the BGIEM function declarations, and any other changes and extensions that may be required. Note that the changes are set up with #if..#endif pairs, so that they will only have effect when compiling an OS/2 program. You can still use the modified graphics.h file to compile programs with a DOS compiler. Note: The original graphics.h file is saved as graphics.bak. If you have a non-standard setup, the easiest thing to do is simply create a directory structure which contains lib and include subdirectories. Put graphics.h in the include subdirectory and run the install script. You can then move the bgi.lib and the modified graphics.h files to your lib and include directories. ═══ 4. How to Use BGIEM ═══ How to Use BGIEM ───────────────────────────────────────────────────────────────────────────── Once you have BGIEM installed, it is very simple to use. The following are the crucial steps: 1. You must include the file graphics.h in any source file in which you call the BGI functions (if you are porting code, this will already be done). 2. You must rename the main() function of the program to bgiem_main() 3. You must link the bgi.lib library with the program after compiling it. That's all there really is to it. Of course, you will have to be aware of other porting considerations when going from a 16-bit compiler to a 32-bit compiler. Int's are now 32 bits instead of 16, and if your code has any dependencies on the size of the data types you may have problems. Note: Although it may appear that your program has no main function, it actually does. The main function is in bgi.lib, as it has to do some setup before your program code begins. Warning: bgiem_main does not currently pass command line parameters in argp and argc the way main does. This will be corrected in the next release. Here is an example of a simple program that starts emulation in VGA mode (640x460x16) and draws a line on the screen. #include bgiem_main() { int driver,mode; driver=VGA; mode=VGAHI; initgraph(&gdriver,&gmode,NULL); line (0,0,100,100); closegraph(); } ═══ 5. Supported Features ═══ Supported Features ───────────────────────────────────────────────────────────────────────────── The supported features list is pretty short for this release. Basically, all of the functions listed in Functions Currently Supported are supported (some only partially) and not much else. Currently, only a single initgraph call per program is supported. See Future Directions for features that will be supported in upcoming versions. ═══ 6. Future Directions ═══ Future Directions ───────────────────────────────────────────────────────────────────────────── The following list is items that will definitely be part of the package in the final release (in no particular order of priority): o Support for argc, argp, and env arguments in bgiem_main. o Support for viewports and all related functions. o Support for image get and put functions. o Support for active/visible pages. o Greater program control over the emulation. For example, currently all operations to the screen are also duplicated on an in-memory bitmap, so that when re-paints are required, the information in the bitmap can be copied to the screen. However, for programs which refresh the screen image frequently this is unneccesary overhead. This, and other aspects of the emulation will be controllable with extra functions provided. o Fix window sizing problems (espcially maximize problem). o Ability to cut and paste graphics from a BGIEM window to/from the clipboard. o Functions to return the window handle and presentation spaces being used by BGIEM so that the program can optionally use more sophisticated presentation managers functions. o Proper error handling, and emulation of graphresult. o Tuning and performance enhancements. The following are features which may find their way into the final release if time permits, and if interest is indicated. o Permit multiple initgraph calls which will open multiple windows simultaneously, and provide functions to change which one will be drawn in. o Permit user-definable graphics modes to emulate. User will be able to chose resolution, number of colours, and number of pages. o Allow the user-program to hook into the BGIEM window message queue, and optionally handle some of the messages received. o Simulate text mode output in the emulated graphics window. o Simulate the standard keyboard input commands (which will not work in a presentation manager program). This one is pretty important actually, and will almost certainly be done. o Provide an interface to the mouse. (Any suggestions on the design of the API for this would be welcome). o Other suggestions are welcome! ═══ 7. How To Report Problems ═══ How To Report Problems ───────────────────────────────────────────────────────────────────────────── Please report problems electronically, by sending mail to one of the following addresses: Compuserve: 71005,132 Internet: rob.mcdermid@rose.com Both suggestions and bug reports are welcome. Before reporting a bug, please study Functions Currently Supported to make sure that it is not simply something not implemented yet. When reporting bugs, a detailed description is always helpful, and code indicating the problem is extremely helpful. Also, when looking for bugs, please note that wherever there was a discrepancy between the documented behaviour of BGI, and how it was actually found to behave, the actual behaviour was emulated. Also, the version being emulated is that shipped with Borland C++ 3.0, so any behaviour changes in 3.1 will not be reflected. ═══ 8. Functions Currently Supported ═══ Functions Currently Supported ───────────────────────────────────────────────────────────────────────────── The functions highlighted in green are currently supported. Double click on the word to jump to a description of the function and its implementation. Functions in blue are not supported, and do not link to a description. ■arc ■bar ■bar3d ■circle ■cleardevice ■clearviewport ■closegraph ■detectgraph ■drawpoly ■ellipse ■fillellipse ■fillpoly ■floodfill ■getarccoords ■getaspectratio ■getbkcolor ■getcolor ■getdefaultpalette ■getdrivername ■getfillpattern ■getfillsettings ■getgraphmode ■getimage ■getlinesettings ■getmaxcolor ■getmaxmode ■getmaxx ■getmaxy ■getmodename ■getmoderange ■getpalette ■getpalettesize ■getpixel ■gettextsettings ■getviewsettings ■getx ■gety ■graphdefaults ■grapherrormsg ■_graphfreemem ■_graphgetmem ■graphresult ■imagesize ■initgraph ■installuserdriver ■installuserfont ■line ■linerel ■lineto ■moverel ■moveto ■outtext ■outtextxy ■pieslice ■putimage ■putpixel ■rectangle ■registerbgidriver ■registerbgifont ■restorecrtmode ■sector ■setactivepage ■setallpalette ■setaspectratio ■setbkcolor ■setcolor ■setfillpattern ■setfillstyle ■setgraphbufsize ■setgraphmode ■setlinestyle ■setpalette ■setrgbpalette ■settextjustify ■settextstyle ■setusercharsize ■setviewport ■setvisualpage ■setwritemode ■textheight ■textwidth ═══ 9. Reference ═══ Reference ───────────────────────────────────────────────────────────────────────────── This section describes the function calls that are emulated, as well as some emulator specific calls. ═══ 9.1. arc ═══ void arc(int x,int y,int stangle,int endangle, int radius) ───────────────────────────────────────────────────────────────────────────── Draws an arc in the current colour. The arc is centered on (x,y), and its radius is specified by radius. The arc travels from stangle to endangle (specified in degrees). The angle increases in a counterclockwise direction, with 0 degrees at 3 o'clock. Note: In BGI the linestyle parameter does not affect arcs, circles, ellipses, or pie slices. Only the thicknessparameter is used. This behaviour is maintained in the emulation. Status: Mostly working. No error checking, and should be optimized. Related Functions: circle ellipse fillellipse getarccoords getaspectratio graphresult pieslice sector ═══ 9.2. bar ═══ void bar(int left,int top,int right,int bottom) ───────────────────────────────────────────────────────────────────────────── Draws a filled, rectangular bar using the current fill pattern and fill color. The bar is not outlined; to draw an outlined two-dimensional bar, use bar3d with depth=0. The upper-left and lower right corners of the bar are specified by (left,top) and (right,bottom). Status: Working. Related Functions: bar3d rectangle setcolor setfillstyle setlinestyle ═══ 9.3. bar3d ═══ void bar3d(int left,int top,int right,int bottom,int depth,int topflag) ───────────────────────────────────────────────────────────────────────────── Draws a 3-dimensional rectangular bar using the current linestyle and colour, then fills it using the current fill style and colour. The depth of the bar along the Z axis is given by depth. The topflag parameter determines whether a 3-dimensional top is put on the bar. It is useful to omit the top of the bar, when drawing a stacked 3-dimensional bar. The way depth is handled is that the 3-dimensional part of the bar is drawn to depth pixels to the right and up from the right corners of the bar. Status: Working. Related Functions: bar rectangle setcolor setfillstyle setlinestyle ═══ 9.4. circle ═══ void circle(int x,int y,int radius) ───────────────────────────────────────────────────────────────────────────── Draws a circle using the current line colour. The circle is centered on (x,y) with radius radius Note: In BGI the linestyle parameter does not affect arcs, circles, ellipses, or pie slices. Only the thicknessparameter is used. This behaviour is maintained in the emulation. Status: Working. Related Functions: arc ellipse fillellipse getaspectratio sector setaspectratio ═══ 9.5. cleardevice ═══ void cleardevice(void) ───────────────────────────────────────────────────────────────────────────── In BGI this erases the entire graphics screen to the currently specified background colour, and moves the current position to (0,0). In BGIEM, the entire window is erased (the CP is also zeroed). Status: Working. Related Functions: clearviewport ═══ 9.6. ═══ Note: This function is not currently supported ═══ 9.7. closegraph ═══ void closegraph(void) ───────────────────────────────────────────────────────────────────────────── Frees up various resources that have been allocated by initgraph. In BGI, ends graphics mode. Currently, the window containing the graphics remains on the screen until the user explicitly shuts down the program. Eventually, the programmer will have more complete behaviour over what initgraph and closegraph actually do. Status: Minimal functionality. Related Functions: initgraph setgraphbufsize ═══ 9.8. ═══ Note: This function is not currently supported ═══ 9.9. drawpoly ═══ void drawpoly(int numpoints, int *polypoints) ───────────────────────────────────────────────────────────────────────────── Draws a polygon specified by numpoints points (each point is a vertex). *polypoints points to a sequence of numpointsx 2 integers. Each pair of integers gives the x and y coordinates of a vertex on the polygon. Note: The polygon is not automatically closed. In order to close the polygon, the last vertex must be the same as the first. Status: Working Related Functions: fillpoly floodfill graphresult setwritemode ═══ 9.10. ellipse ═══ void ellipse(int x,int y,int stangle,int endangle,int xradius,int yradius) ───────────────────────────────────────────────────────────────────────────── Draws an elliptical arc in the current drawing colour. The ellipse is centered on (x,y) and the lengths of the horizontal and vertical axes are given by xradius and yradius respectively. The ellipse travels from stangle to endangle (specified in degrees). The angle increases in a counterclockwise direction, with 0 degrees at 3 o'clock. If stangle=0 and endangle=360, then a complete ellipse is drawn. Note: In BGI the linestyle parameter does not affect arcs, circles, ellipses, or pie slices. Only the thicknessparameter is used. This behaviour is maintained in the emulation. Status: Working Related Functions: arc circle fillellipse sector ═══ 9.11. fillellipse ═══ void fillellipse(int x,int y,int xradius,int yradius) ───────────────────────────────────────────────────────────────────────────── Draws an ellipse centered on (x,y) with a width of xradius and a height of yradius, and fills it with the current fill colour and fill pattern. The ellipse is outlined using the current line color and width. Status: Working Related Functions: arc circle ellipse pieslice ═══ 9.12. fillpoly ═══ void fillpoly(int numpoints,int *polypoints) ───────────────────────────────────────────────────────────────────────────── Draws the outline of a polygon using the current line style and colour, like drawpoly, then fills the polygon using the current fill pattern and fill colour. *polypoints points to a sequence of numpointsx 2 integers. Each pair of integers gives the x and y coordinates of a vertex on the polygon. Status: Working Related Functions: drawpoly floodfill graphresult setfillstyle ═══ 9.13. floodfill ═══ void floodfill(int x,int y,int border) ───────────────────────────────────────────────────────────────────────────── Fills an arbitrary enclosed area using the current fill pattern and colour. (x,y) must be a point somewhere inside the area to be filled. The area bounded by the colour border is filled. Status: Working Related Functions: drawpoly fillpoly graphresult setcolor setfillstyle ═══ 9.14. getarccoords ═══ void getarccoords(struct arccoordstype arccoords) ───────────────────────────────────────────────────────────────────────────── Fills in the arccoordstype structure pointed to by arccoords with information from the last call to arc. The arccoordstype structure is defined (in graphics.h) as: struct arccoordstype { int x,y; int xstart, ystart, xend, yend; }; The information in this structure defines the center point (x,y), the start point (xstart,ystart), and the end point (xend,yend). Status: Complete. Related Functions: arc fillellipse sector ═══ 9.15. ═══ Note: This function is not currently supported ═══ 9.16. getbkcolor ═══ int getbkcolor(void) ───────────────────────────────────────────────────────────────────────────── Returns the current background colour. Status: Complete. Related Functions: getcolor getmaxcolor getpalette setbkcolor ═══ 9.17. getcolor ═══ int getcolor(void) ───────────────────────────────────────────────────────────────────────────── Returns the current line drawing color. Status: Complete. Related Functions: getbkcolor getmaxcolor getpalette setcolor ═══ 9.18. ═══ Note: This function is not currently supported ═══ 9.19. ═══ Note: This function is not currently supported ═══ 9.20. getfillpattern ═══ void getfillpattern(char *pattern) ───────────────────────────────────────────────────────────────────────────── Copies the user-defined fill pattern, previously set by the routine setfillpattern into the 8 byte memory area pointed to by pattern. Each byte in pattern corresponds to 8 pixels in the pattern. Whenever a bit is 1, the pixel in the pattern will be set. Status: Complete, but inefficient. Requires a more efficient algorithm. Related Functions: getfillsettings setfillpattern ═══ 9.21. getfillsettings ═══ void getfillsettings(struct fillsettingstype *fillinfo) ───────────────────────────────────────────────────────────────────────────── Gets the current fill pattern and colour and puts them in the structure pointed to by fillinfo. The fillsettingstype structure is defined as: struct fillsettingstype { int pattern; int color; }; If the current fill pattern is one of pre-defined fill patterns, its number will be stored in fillinfo->pattern. If the current fill pattern is a user-defined pattern, the USER_FILL will be stored in fillinfo->pattern. Status: Complete. Related Functions: getfillpattern setfillpattern setfillstyle ═══ 9.22. getgraphmode ═══ int getgraphmode(void) ───────────────────────────────────────────────────────────────────────────── Gets the current graph mode. A successful call to initgraph is required before valid results can be returned from this function. Status: Complete. Related Functions: getmoderange restorecrtmode setgraphmode ═══ 9.23. ═══ Note: This function is not currently supported ═══ 9.24. getlinesettings ═══ void getlinesettings(struct linesettingstype *lineinfo) ───────────────────────────────────────────────────────────────────────────── Gets information about the current linestyle and thickness in the structure pointed to by lineinfo. The linesettingstype structure is defined as: struct linesettingstype { int linestyle; unsigned upattern; int thickness; }; Currently, user-defined linestyles are not supported, so the value of the upattern field is not defined. Status: Complete. Related Functions: setlinestyle ═══ 9.25. getmaxcolor ═══ int getmaxcolor(void) ───────────────────────────────────────────────────────────────────────────── Returns the maximum color value permitted for the mode currently being emulated. Does not necessarily relate to the maximum number of color values that the screen hardware can display. Note that if you pass a colour value higher than this to setcolor, the actual color will be calculated as requested_color % maximum_color Status: Complete. Related Functions: getbkcolor getcolor getpalette getpalettesize setcolor ═══ 9.26. getmaxmode ═══ int getmaxmode(void) ───────────────────────────────────────────────────────────────────────────── Returns the maximum mode number that may be specified for the driver currently being emulated. The minimum value it will return is 0. Status: Complete. Related Functions: getmodename getmoderange ═══ 9.27. getmaxx ═══ int getmaxx(void) ───────────────────────────────────────────────────────────────────────────── Returns the maximum permitted x-coordinate value for the graphics mode currently being emulated. Status: Complete. Related Functions: getmaxy getx gety ═══ 9.28. getmaxy ═══ int getmaxy(void) ───────────────────────────────────────────────────────────────────────────── Returns the maximum permitted y-coordinate value for the graphics mode currently being emulated. Status: Complete. Related Functions: getmaxx getx gety ═══ 9.29. ═══ Note: This function is not currently supported ═══ 9.30. getmoderange ═══ void getmaxmode(int graphdriver,int *lomode,int *himode) ───────────────────────────────────────────────────────────────────────────── Gets the range of valid graphics modes for a given driver. The lowest allowed mode value is returned in lomode and the highest in himode. If a value of -1 is specified for graphdriver the modes for the currently loaded driver are given. If any other negative value is specified, -1 is given for both lomode and himode. Currently, no checking is done to see if the value for graphdriver is too high. Status: Complete, except possibly for some error checking. Related Functions: getgraphmode getmaxmode getmodename initgraph setgraphmode ═══ 9.31. ═══ Note: This function is not currently supported ═══ 9.32. ═══ Note: This function is not currently supported ═══ 9.33. ═══ Note: This function is not currently supported ═══ 9.34. gettextsettings ═══ void gettextsettings(struct textsettingstype *texttypeinfo) ───────────────────────────────────────────────────────────────────────────── Returns information about the current font. The textsettingstype structure is defined as: struct textsettingstype { int font; int direction; int charsize; int horiz; int vert; } font is the currently selected font number, direction is the current text direction, charsize is the scaling factor, horiz is the horizontal alignment, and vert is the vertical alignment. Status: Complete. Related Functions: outtext outtextxy registerbgifont settextjustify settextstyle setusercharsize textheight textwidth ═══ 9.35. ═══ Note: This function is not currently supported ═══ 9.36. getx ═══ int getx(void) ───────────────────────────────────────────────────────────────────────────── Returns the x coordinate of the graphics cursor current position. Status: Will need to be adapted when viewports are implemented. Related Functions: getmaxx getmaxy getviewsettings gety moveto ═══ 9.37. gety ═══ int getx(void) ───────────────────────────────────────────────────────────────────────────── Returns the y coordinate of the graphics cursor current position. Status: Will need to be adapted when viewports are implemented. Related Functions: getmaxx getmaxy getviewsettings getx moveto ═══ 9.38. ═══ Note: This function is not currently supported ═══ 9.39. ═══ Note: This function is not currently supported ═══ 9.40. <_graphfreemem> ═══ Note: This function is not currently supported ═══ 9.41. <_graphgetmem> ═══ Note: This function is not currently supported ═══ 9.42. ═══ Note: This function is not currently supported ═══ 9.43. ═══ Note: This function is not currently supported ═══ 9.44. initgraph ═══ initgraph(int *driver,int *mode,int *pathtodriver) ───────────────────────────────────────────────────────────────────────────── In BGI, initializes the graphics system by loading a driver and putting the system in graphics mode. In BGIEM, the initgraph/closegraph pair is not yet working as intended. Currently, a new window is created as soon as the program starts. Initgraph merely performs some initialization functions. Closegraph does not cause the window to disappear, and it does not yet fully clean up after initgraph. Eventually, the intention is to have initgraph open a new window. Closegraph will optionally destroy that window, or leave it until the user destroys it. A subsequent initgraph will open a new window, possibly emulating a different mode. However, some technical issues remain to be resolved before this can be done. BGIEM simulates the resolution and colour range of the mode selected. With the exception of the 8514 modes, all of the modes emulated are 16 color or less, which means that they can be accurately simulated on any of the hardware supported by OS/2. 256 color modes will be supported by dithering on 16 color hardware, or exactly on 16 color hardware. This has not been tested yet, however. Currently, the initial window size is determined by the operating system. When the window is created, if it is too small to display the entire emulated window, scroll bars are created to allow the user to see the entire emulated graphic area. This area of behaviour is only loosly implemented so far, so do not be surprised by strange behaviour. Note: The pathtodriver parameter is ignored, since no drivers are actually loaded. Also, because of this, you cannot use any custom drivers that may have been implemented. Some time in the future, BGIEM will allow user-defined modes to be created with custom pixel and colour resolution. Note: Autodetection is not yet supported. Status: Partially implemented. Major behaviour changes to come. Related Functions: closegraph detectgraph getdefaultpalette getdrivername getgraphmode getmoderange graphdefaults _graphgetmem graphresult installuserdriver registerbgidriver registerbgifont restorecrtmode setgraphbufsize setgraphmode ═══ 9.45. ═══ Note: This function is not currently supported ═══ 9.46. ═══ Note: This function is not currently supported ═══ 9.47. line ═══ void line(int x1,int y1,int x2,int y2) ───────────────────────────────────────────────────────────────────────────── Draws a line in the current colour and linestyle between (x1,y1) and (x2,y2). The current position is not updated. Status: Working. Related Functions: getlinesettings linerel lineto setcolor setlinestyle setwritemode ═══ 9.48. linerel ═══ void linerel(int dx,int dy) ───────────────────────────────────────────────────────────────────────────── Draws a line from the current position to a relative position that is (dx,dy) away. Ie, if the current position is (x,y), then the line is drawn from (x,y) to (x+dx,y+dy). The current position is updated to the line end point. Status: Working. Related Functions: getlinesettings line lineto setcolor setlinestyle setwritemode ═══ 9.49. lineto ═══ void lineto(int x,int y) ───────────────────────────────────────────────────────────────────────────── Draws a line from the current position to (x,y) and updates the current position to (x,y). Status: Working. Related Functions: getlinesettings line linerel setcolor setlinestyle setwritemode ═══ 9.50. moverel ═══ void moverel(int dx,int dy) ───────────────────────────────────────────────────────────────────────────── Moves the current position dx pixels in the x direction and dydy pixels in the y direction. Status: Working. Related Functions: moveto ═══ 9.51. moveto ═══ void moveto(int x,int y) ───────────────────────────────────────────────────────────────────────────── Moves the current position to (x,y). Status: Working. Related Functions: moverel ═══ 9.52. outtext ═══ void outtext(char *textstring) ───────────────────────────────────────────────────────────────────────────── Displays a text string using the current font, font direction, font size, and the current text justification settings. The text is output at the current position. If the horizontal justification is LEFT_TEXT and the text direction is HORIZ_DIR the x-coordinate of the current position is increased by textwidth(textstring) Otherwise, the current position is not changed. Status: Working. Related Functions: gettextsettings outtextxy settextjustify textheight textwidth ═══ 9.53. outtextxy ═══ void outtextxy(int x,int y,char *textstring) ───────────────────────────────────────────────────────────────────────────── Displays a text string using the current font, font direction, font size, and the current text justification settings at the position specified by (x,y). Status: Working. Related Functions: gettextsettings outtext settextjustify textheight textwidth ═══ 9.54. pieslice ═══ void pieslice(int x,int y,int stangle,int endangle, int radius) ───────────────────────────────────────────────────────────────────────────── Draws a pieslice (sector of a circle) centered at (x,y) with a radius of radius The pieslice is drawn in the current colour and font, and filled using the current fill pattern and colour. The slice travels from stangle to endangle The angle increases in a counterclockwise direction, with 0 degrees at 3 o'clock. Note: In BGI the linestyle parameter does not affect arcs, circles, ellipses, or pie slices. Only the thicknessparameter is used. This behaviour is maintained in the emulation. Status: Working. Related Functions: fillellipse graphresult sector setfillstyle ═══ 9.55. ═══ Note: This function is not currently supported ═══ 9.56. putpixel ═══ void putpixel(int x,int y,int color) ───────────────────────────────────────────────────────────────────────────── Sets the pixel at the specified (x,y) coordinates to the specified colour. Does not alter the current drawing color or the current position. Status: Complete except for error handling Related Functions: getpixel putimage ═══ 9.57. rectangle ═══ void rectangle(int left,int top,int right,int bottom) ───────────────────────────────────────────────────────────────────────────── Draws a rectangle using the current line style, thickness and colour. (left,top) is the upper left corner, and (right,bottom) is the lower right corner. Status: Complete except for error handling Related Functions: bar bar3d setcolor setlinestyle ═══ 9.58. ═══ Note: This function is not currently supported ═══ 9.59. ═══ Note: This function is not currently supported ═══ 9.60. ═══ Note: This function is not currently supported ═══ 9.61. sector ═══ void sector(int x,int y,int stangle,int endangle,int xradius,int yradius) ───────────────────────────────────────────────────────────────────────────── Draws and fills an elliptical pie slice. (x,y) is the center point, xradius is the width, yradius is the height, and the angle sweeps from stangle to endangle. The sector is outlined using the current line settings, and filled using the current fill pattern and colour. The angle increases in a counterclockwise direction, with 0 degrees at 3 o'clock. Note: In BGI the linestyle parameter does not affect arcs, circles, ellipses, or pie slices. Only the thicknessparameter is used. This behaviour is maintained in the emulation. Status: Complete except for error handling Related Functions: arc circle ellipse getarccoords getaspectratio graphresult pieslice setfillpattern setfillstyle setgraphbufsize ═══ 9.62. ═══ Note: This function is not currently supported ═══ 9.63. ═══ Note: This function is not currently supported ═══ 9.64. ═══ Note: This function is not currently supported ═══ 9.65. setbkcolor ═══ void setbkcolor(int color) ───────────────────────────────────────────────────────────────────────────── Sets the background color to color. Status: Working Related Functions: getbkcolor setallpalette setcolor setpalette ═══ 9.66. setcolor ═══ void setcolor(int color) ───────────────────────────────────────────────────────────────────────────── Sets the current colour to color, which can range from 0 to getmaxcolor(). Status: Working Related Functions: getcolor getmaxcolor graphresult setallpalette setbkcolor setpalette ═══ 9.67. setfillpattern ═══ void setfillpattern(char *upattern,int color) ───────────────────────────────────────────────────────────────────────────── Sets the current fillstyle to the user-defined pattern specified by upattern. upattern is a pointer to an array of 8 bytes. Each byte corresponds to one row in the pattern, with each pixel value of 1 representing a pixel that is on in the pattern. The fill pattern colour is set to color. To change the fillstyle back to one of the pre-defined styles, call setfillstyle. Status: Complete except for error handling and optimization. Currently the method being used to transfer the pattern from upattern to presentation manager format is very simplistic, and can be sped up considerably. Related Functions: bar getfillpattern getfillsettings graphresult sector setfillstyle ═══ 9.68. setfillstyle ═══ void setfillstyle(int pattern,int color) ───────────────────────────────────────────────────────────────────────────── Sets the current fillstyle to the style specified by pattern, and the current fill color to color Currently, the pre-defined Borland fill styles are mapped on to the pre-defined PM fill styles in the default style set. The match is very close, the only exception being the WIDE_DOT_FILL style, which is currently the same as CLOSE_DOT_FILL. The USER_FILL pattern should not be used to specify a user-defined pattern, instead call setfillpattern. Status: Complete except for error handling Related Functions: bar bar3d fillpoly floodfill getfillsettings graphresult pieslice sector setfillpattern ═══ 9.69. ═══ Note: This function is not currently supported ═══ 9.70. ═══ Note: This function is not currently supported ═══ 9.71. setlinestyle ═══ void setlinestyle(int linestyle,unsigned upattern,int thickness) ───────────────────────────────────────────────────────────────────────────── Sets the linestyle for all lines drawn. Linestyle may be one of the following: o SOLID_LINE* o DOTTED_LINE* o CENTER_LINE* o DASHED_LINE* o DOUBLEDOT_LINE o LONGDASH_LINE o DASHDOUBLEDOT_LINE o INVISIBLE_LINE o ALTERNATE_LINE Note: The linestyles marked with an asterix (*) are those defined by BGI. These were mapped onto the Presentation Manager pre-defined linestyles that most closely matched the BGI ones. The other linestyles are those in Presentation Manager that have no BGI analog. Do not use these in code that you want to be backwards compatible to DOS. thickness specifies the width of subsequent lines. It can be either NORM_WIDTH - 1 pixel wide, or THICK_WIDTH - 3 pixels wide. This parameter is currently not supported because Presentation Manager does not support thick lines and line patterns at the same time. Hopefully, a workaround for this will be found before final release. upattern is not supported in BGIEM, because OS/2 does not support user-defined linestyles. Status: Working. No error handling. Still need support for thickness parameter. Related Functions: arc bar3d circle drawpoly ellipse getlinesettings graphresult line linerel lineto pieslice rectangle ═══ 9.72. ═══ Note: This function is not currently supported ═══ 9.73. ═══ Note: This function is not currently supported ═══ 9.74. settextjustify ═══ void settextjustify(int horiz,int vert) ───────────────────────────────────────────────────────────────────────────── Sets how text is justified with respect to the current position (for outtext) or the specified drawing position (for outtextxy). The default settings are LEFT_TEXT for horiz and TOP_TEXT for vert. The following are the valid values: Description Name Value Action ┌──────────┬────────────────────┬─────┬──────────────────────────────┐ │horiz │LEFT_TEXT │0 │left-justify text │ ├──────────┼────────────────────┼─────┼──────────────────────────────┤ │ │CENTER_TEXT │1 │center text │ ├──────────┼────────────────────┼─────┼──────────────────────────────┤ │ │RIGHT_TEXT │2 │right-justify text │ ├──────────┼────────────────────┼─────┼──────────────────────────────┤ │vert │BOTTOM_TEXT │0 │justify from bottom │ ├──────────┼────────────────────┼─────┼──────────────────────────────┤ │ │CENTER_TEXT │1 │center text │ ├──────────┼────────────────────┼─────┼──────────────────────────────┤ │ │TOP_TEXT │2 │justify from top │ └──────────┴────────────────────┴─────┴──────────────────────────────┘ Status: Working. No error handling. Related Functions: gettextsettings graphresult outtext settextstyle ═══ 9.75. settextstyle ═══ void settextstyle(int font,int direction,int charsize) ───────────────────────────────────────────────────────────────────────────── Sets the font, direction, and scaling factors for text. The BGI implementation that came with BC++ 3.0 offered quite a few stroked fonts. For each of these, an attempt was made to match them with one of the fonts that comes with OS/2 version 2.1 that looks similar. Each of the OS/2 fonts is scaled to look about the same size as the BGI font. Later, it will be possible to set up other fonts installed under OS/2 to be accessible with this function call, but this is not supported yet. For the DEFAULT_FONT, which is a bit-mapped font, the VIO 8x8 font was mapped to it. Currently, scaling is not supported for this font in BGIEM, but it is supported for all of the "stroked" fonts, which are emulated using the Adobe scalabale fonts. direction may be horizontal text (left to right) or vertical text (rotated 90 degrees counterclockwise). These are specified as either HORIZ_DIR, or VERT_DIR. charsize specifies the scaling for each font. Scaling of bit-mapped fonts is not currently supported. For scaling of stroked or scalable fonts, only two values are valid: 0, and 1. A value of 1 specifies the default size for the font, while a value of 0 specifies that the scaling should be taken from setusercharsize. Note: Although it is not documented to work this way, it appears that when BGI uses a charsize of 0 the usercharsize defaults to 1/1 for both x and y, but when charsize is 0, the size is equivalent to a usercharsize of 3/2 for both x and y. The behaviour of BGIEM reflects the observed actual behaviour, rather than the documented behaviour. Status: Working. No error handling. Would like to figure out a way to scale the bitmap font. Related Functions: gettextsettings graphresult installuserfont settextjustify setusercharsize textheight textwidth ═══ 9.76. setusercharsize ═══ void setusercharsize(int multx,int divx,int multy,int divy) ───────────────────────────────────────────────────────────────────────────── Specify multiply and divide factors to scale the text font by. The default width is scaled by multx/divx and the default height is scaled by multy/divy These settings only take effect if charsize equals 0, as set by a call to settextstyle. Status: Working. No error handling. Related Functions: gettextsettings graphresult settextstyle ═══ 9.77. ═══ Note: This function is not currently supported ═══ 9.78. ═══ Note: This function is not currently supported ═══ 9.79. setwritemode ═══ void setwritemode(int mode) ───────────────────────────────────────────────────────────────────────────── Sets the write mode to mode. There are two styles defined: o COPY_PUT = 0 o XOR_PUT = 1 When the write mode is COPY_PUT, the line drawn overwrites whatever is on the screen. When the write mode is XOR_PUT, the line is exclusive or'd with whatever is on the screen. The write mode only affects the line, linerel, lineto, rectangle, and drawpoly functions. Status: Complete. Related Functions: drawpoly line linerel lineto rectangle ═══ 9.80. textheight ═══ int textheight(char *textstring) ───────────────────────────────────────────────────────────────────────────── Determines the height of textstring in pixels, based on the currently selected font and scaling factor. Status: Complete. Related Functions: gettextsettings outtext outtextxy settextstyle textwidth ═══ 9.81. textwidth ═══ int textwidth(char *textstring) ───────────────────────────────────────────────────────────────────────────── Determines the width of textstring in pixels, based on the currently selected font and scaling factor. Status: Complete. Related Functions: gettextsettings outtext outtextxy settextstyle textheight