@#
@# This is the source for the Allegro common mistakes, in a weird custom
@# format. Read makedoc.c for a description of what is going on...
@#
@external-css=allegro.css
@document_title=Common mistakes
<center><h1><b>
Common mistakes
</b></h1></center>
<hr>

@!text
@heading
Contents

@shortcontents

@text

@@   Ignoring this manual.
      Most problems are addressed in this manual. If you aren't sure about
      some parts of Allegro check particular section of manual. The FAQ
      section can also be very useful.

@@   main() not returning int.
      On platforms that need it, Allegro uses <code>END_OF_MAIN</code> to
      mangle your main() function and supply its own that is required by the
      platform. Allegro assumes that main() returns an integer, as required
      by various C standards. If you change the return type of your main() to
      something else Allegro's main() will get confused and return some
      nonsense value which some system can recognize as an error and crash
      your program.

@@   Semicolon at END_OF_MAIN.
<codeblock>
         int main(void)
         {
            allegro_init();
            /* more stuff goes here */
            ...
            return 0;
         }
         END_OF_MAIN(); /* wrong */ <endblock>

      The semicolon is not only unnecessary after END_OF_MAIN(), but it can
      also cause some compilers to issue a warning.

@@   Getting bitmap's size.
      Many people don't know how to get the dimensions of a bitmap. This can
      be done by accessing the `w' and `h' fields of the BITMAP structure:
<codeblock>
         BITMAP *image;
         ...
         allegro_message("Bitmap size: %d x %d\n",
                         image-&gtw, image-&gth);<endblock>

@@   Creating bitmaps before loading.
<codeblock>
         BITMAP *image = create_bitmap(width, height);
         image = load_bitmap("image.bmp", pal);<endblock>

      When loading a bitmap, Allegro will automatically create a bitmap big
      enough to store it. In the above code the address returned by
      create_bitmap() is overwritten by the second assignment statement, to
      the return value of the call to load_bitmap().  Since the address of
      the first (unnecessary) bitmap has been lost, there is no way to
      destroy it so there is a memory leak.

@@   Loading a bitmap/font/sound inside a global object constructor.
      Almost all Allegro functions require Allegro to be initialized first,
      before they can be used. Since global object constructors are called
      before main() (from where <code>allegro_init()</code> would be called) this
      condition is violated.  You need to postpone calls to Allegro functions
      to after initializing Allegro.

@@   Calling set_color_depth without resetting graphic mode.
      <code>set_color_depth()</code> tells Allegro which color depth to use the <em>next</em> time a
      graphic mode is set or bitmap is created or loaded. It doesn't change
      the color depth of the current graphic mode or existing bitmaps.  You
      need to be sure that all your bitmaps and/or graphic mode are in the
      same color depth or Allegro will be forced to do slow color conversions
      between them.

@@   Destroying global objects like `screen'.
      Unlike other bitmaps `screen' is created by calling <code>set_gfx_mode()</code> and
      must not be destroyed by calling <code>destroy_bitmap()</code>. The proper way to
      destroy `screen' is calling <code>set_gfx_mode(GFX_TEXT, 0, 0, 0, 0)</code>.