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.


Mail converted by MHonArc 2.6.19+ http://listengine.tuxfamily.org/