| Re: [AD] First batch of doc changes |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
And here's several more.
Evert
Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.337
diff -u -r1.337 allegro._tx
--- docs/src/allegro._tx 3 Jun 2005 16:39:31 -0000 1.337
+++ docs/src/allegro._tx 5 Jun 2005 12:59:02 -0000
@@ -4753,6 +4753,9 @@
is locked, which prevents them from getting any input messages, so you
must be sure to release all your bitmaps before using any timer,
keyboard, or other non-graphics routines!
+
+ Note that if you are using hardware accelerated VRAM->VRAM blits, you should
+ not call acquire_bitmap().
@@void @release_bitmap(BITMAP *bmp);
@xref acquire_bitmap, acquire_screen, release_screen
Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.337
diff -u -r1.337 allegro._tx
--- docs/src/allegro._tx 3 Jun 2005 16:39:31 -0000 1.337
+++ docs/src/allegro._tx 5 Jun 2005 13:24:04 -0000
@@ -4897,7 +4897,19 @@
@xref load_bmp
@eref expackf
@shortdesc Packfile version of load_bmp.
- A version of load_bmp which reads from a packfile.
+ A version of load_bmp which reads from a packfile. Example:
+<codeblock>
+ PACKFILE *f;
+ BITMAP *bmp;
+
+ f = pack_fopen("mybitmap.bmp", F_READ);
+ bmp = load_bmp_pf(f, pal);
+ pack_fclose(f);</endblock>
+
+@retval
+ Returns a pointer to the bitmap or NULL on error. Remember that you are
+ responsible for destroying the bitmap when you are finished with it to
+ avoid memory leaks.
@@BITMAP *@load_lbm(const char *filename, RGB *pal);
@xref load_bitmap
@@ -4922,7 +4934,18 @@
@xref load_pcx
@eref expackf
@shortdesc Packfile version of load_pcx.
- A version of load_pcx which reads from a packfile.
+ A version of load_pcx which reads from a packfile. Example:
+<codeblock>
+ PACKFILE *f;
+ BITMAP *bmp;
+
+ f = pack_fopen("mybitmap.pcx", F_READ);
+ bmp = load_bmp_pf(f, pal);
+ pack_fclose(f);</endblock>
+@retval
+ Returns a pointer to the bitmap or NULL on error. Remember that you are
+ responsible for destroying the bitmap when you are finished with it to
+ avoid memory leaks.
@@BITMAP *@load_tga(const char *filename, RGB *pal);
@xref load_bitmap
@@ -4938,7 +4961,18 @@
@xref load_tga
@eref expackf
@shortdesc Packfile version of load_tga.
- A version of load_tga which reads from a packfile.
+ A version of load_tga which reads from a packfile. Example:
+<codeblock>
+ PACKFILE *f;
+ BITMAP *bmp;
+
+ f = pack_fopen("mybitmap.tga", F_READ);
+ bmp = load_bmp_pf(f, pal);
+ pack_fclose(f);</endblock>
+@retval
+ Returns a pointer to the bitmap or NULL on error. Remember that you are
+ responsible for destroying the bitmap when you are finished with it to
+ avoid memory leaks.
@@int @save_bitmap(const char *filename, BITMAP *bmp, const RGB *pal);
@xref save_bmp, save_pcx, save_tga, load_bitmap, register_bitmap_file_type
@@ -4972,7 +5006,7 @@
@retval
Returns non-zero on error.
-@domain.hid *@save_bmp_pf(PACKFILE *f, RGB *pal);
+@@int @save_bmp_pf(PACKFILE *f, RGB *pal);
@xref save_bmp
@eref expackf
@shortdesc Packfile version of save_bmp.
@@ -4985,7 +5019,7 @@
@retval
Returns non-zero on error.
-@domain.hid *@save_pcx_pf(PACKFILE *f, RGB *pal);
+@@int @save_pcx_pf(PACKFILE *f, RGB *pal);
@xref save_pcx
@shortdesc Packfile version of save_pcx.
A version of save_pcx which writes to a packfile.
@@ -4998,7 +5032,7 @@
@retval
Returns non-zero on error.
-@domain.hid *@save_tga_pf(PACKFILE *f, RGB *pal);
+@@int @save_tga_pf(PACKFILE *f, RGB *pal);
@xref save_tga
@eref expackf
@shortdesc Packfile version of save_tga.
Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.337
diff -u -r1.337 allegro._tx
--- docs/src/allegro._tx 3 Jun 2005 16:39:31 -0000 1.337
+++ docs/src/allegro._tx 5 Jun 2005 12:20:06 -0000
@@ -3546,7 +3546,7 @@
incorrect data.
@@int @install_joystick(int type);
-@domain.hid remove_joystick, load_joystick_data, calibrate_joystick
+@xref remove_joystick, num_joysticks, load_joystick_data, calibrate_joystick
@xref calibrate_joystick_name, poll_joystick, Standard config variables
@xref JOY_TYPE_*/DOS, JOY_TYPE_*/Windows, JOY_TYPE_*/Linux
@eref exjoy
@@ -3555,7 +3555,13 @@
type parameter should usually be JOY_TYPE_AUTODETECT, or see the platform
specific documentation for a list of the available drivers. You must call
this routine before using any other joystick functions, and you should
- make sure that the joystick is in the middle position at the time.
+ make sure that the joystick is in the middle position at the time. Example:
+<codeblock>
+ if (install_joystick(JOY_TYPE_AUTODETECT) != 0) {
+ set_gfx_mode(GFX_TEXT, 0, 0, 0, 0);
+ allegro_message("Error initialising joystick\n%s\n", allegro_error);
+ return 1;
+ }<endblock>
@retval
Returns zero on success. As soon as you have installed the joystick
module, you will be able to read the button state and digital (on/off
@@ -3575,7 +3581,20 @@
@eref exjoy
@shortdesc Polls the joystick.
The joystick is not interrupt driven, so you need to call this function
- every now and again to update the global position values.
+ every now and again to update the global position values. Example:
+<codeblock>
+ do {
+ /* Get joystick input */
+ poll_joystick();
+
+ /* Process input */
+ if (joy[0].button[0].b)
+ first_button_pressed();
+
+ if (joy[0].button[1].b)
+ second_button_pressed();
+ ...
+ } while(!done);<endblock>
@retval
Returns zero on success or a negative number on failure (usually because
no joystick driver was installed).
Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.337
diff -u -r1.337 allegro._tx
--- docs/src/allegro._tx 3 Jun 2005 16:39:31 -0000 1.337
+++ docs/src/allegro._tx 5 Jun 2005 12:49:31 -0000
@@ -4020,15 +4020,16 @@
When you call set_gfx_mode(), the v_w and v_h parameters represent the
minimum size of virtual screen that is acceptable for your program. The
- range of possible sizes is usually very restricted, and Allegro is likely
- to end up creating a virtual screen much larger than the one you request.
- On an SVGA card with one megabyte of vram you can count on getting a
- 1024x1024 virtual screen (256 colors) or 1024x512 (15 or 16 bpp), and
- with 512k vram you can get 1024x512 (256 colors). Other sizes may or may
- not be possible: don't assume that they will work. In mode-X the virtual
- width can be any multiple of eight greater than or equal to the physical
- screen width, and the virtual height will be set accordingly (the VGA has
- 256k of vram, so the virtual height will be 256*1024/virtual_width).
+ range of possible sizes is usually very restricted, and Allegro may
+ end up creating a virtual screen much larger than the one you request.
+ Allowed sizes are driver dependent and some drivers do not allow virtual
+ screens that are larger than the visible screen at all: don't assume
+ that whatever you pass will always work.
+
+ In mode-X the virtual width can be any multiple of eight greater than or
+ equal to the physical screen width, and the virtual height will be set
+ accordingly (the VGA has 256k of vram, so the virtual height will be
+ 256*1024/virtual_width).
Currently, using a big virtual screen for page flipping is considered bad
practice. There are platforms which don't support virtual screens bigger
@@ -4327,13 +4328,9 @@
original position in the screen bitmap you will have to alter the clipping
rectangle with set_clip_rect().
- Mode-X scrolling is reliable and will work on any card. Unfortunately
- most VESA implementations can only handle horizontal scrolling in four
- pixel increments, so smooth horizontal panning is impossible in SVGA
- modes. A significant number of VESA implementations seem to be very buggy
- when it comes to scrolling in truecolor video modes, so you shouldn't
- depend on this routine working correctly in the truecolor resolutions
- unless you can be sure that SciTech Display Doctor is installed.
+ Mode-X scrolling is reliable and will work on any card, other drivers may
+ not work or not work reliably. See the platform-specific section of the docs
+ for more information.
Allegro will handle any necessary vertical retrace synchronisation when
scrolling the screen, so you don't need to call vsync() before it. This
@@ -4353,12 +4350,9 @@
the poll_scroll() routine to detect when the flip has actually taken
place.
- Triple buffering is only possible on certain hardware: it will work in any
- DOS mode-X resolution if the timer retrace simulator is active (but this
- doesn't work correctly under Windows 95), plus it is supported by the
- VBE 3.0 and VBE/AF drivers for a limited number of high-end graphics
- cards. You can look at the GFX_CAN_TRIPLE_BUFFER bit in the
- gfx_capabilities flag to see if it will work with the current driver.
+ Triple buffering is only possible with certain drivers: you can look at the
+ GFX_CAN_TRIPLE_BUFFER bit in the gfx_capabilities flag to see if it will
+ work with the current driver.
@retval
This function returns zero on success, non-zero otherwise.
@@ -4382,7 +4376,21 @@
Allegro will handle any necessary vertical retrace synchronisation when
page flipping, so you don't need to call vsync() before it. This means
- that show_video_bitmap() has the same time delay effects as vsync().
+ that show_video_bitmap() has the same time delay effects as vsync(). Example:
+<codeblock>
+ int current_page;
+ BITMAP *video_page[2];
+ ...
+ /* Create pages for page flipping */
+ video_page[0] = create_video_bitmap(SCREEN_W, SCREEN_H);
+ video_page[1] = create_video_bitmap(SCREEN_W, SCREEN_H);
+ current_page = 0;
+ ...
+ /* draw the screen and flip pages */
+ draw_screen(video_page[current_page]);
+ show_video_bitmap(video_page[current_page]);
+ current_page = (current_page+1)%2;
+ ...<endblock>
@retval
Returns zero on success and non-zero on failure.
@@ -4397,7 +4405,24 @@
vertical retrace, but you can carry on running other code in the meantime
and use the poll_scroll() routine to detect when the flip has actually
taken place. Triple buffering is only possible on certain hardware: see
- the comments about request_scroll().
+ the comments about request_scroll(). Example:
+<codeblock>
+ int current_page;
+ BITMAP *video_page[3];
+ ...
+ /* Create pages for page flipping */
+ video_page[0] = create_video_bitmap(SCREEN_W, SCREEN_H);
+ video_page[1] = create_video_bitmap(SCREEN_W, SCREEN_H);
+ video_page[2] = create_video_bitmap(SCREEN_W, SCREEN_H);
+ current_page = 0;
+ ...
+ /* draw the screen and flip pages */
+ draw_screen(video_page[current_page]);
+ do {
+ } while (poll_scroll());
+ request_video_bitmap(video_page[current_page]);
+ current_page = (current_page+1)%3;
+ ...<endblock>
@retval
Returns zero on success and non-zero on failure.
@@ -12202,6 +12227,18 @@
normal VESA 640x400 mode will be chosen instead), so if you want to
use it you will have to explicitly pass GFX_XTENDED to set_gfx_mode().
</ul>
+ There are a few things you need to be aware of for scrolling:
+ most VESA implementations can only handle horizontal scrolling in four
+ pixel increments, so smooth horizontal panning is impossible in SVGA modes.
+ A significant number of VESA implementations seem to be very buggy when it
+ comes to scrolling in truecolor video modes, so you shouldn't depend on
+ this routine working correctly in the truecolor resolutions unless you can
+ be sure that SciTech Display Doctor is installed.
+
+ Triple buffering is only possible with certain drivers: it will work in any
+ DOS mode-X resolution if the timer retrace simulator is active (but this
+ doesn't work correctly under Windows 95), plus it is supported by the
+ VBE 3.0 and VBE/AF drivers for a limited number graphics cards.
@@Drivers @DIGI_*/DOS
@xref detect_digi_driver, install_sound, install_sound_input
@shortdesc Supported DOS digital sound drivers.