Sophie

Sophie

distrib > Arklinux > devel > x86_64 > media > main > by-pkgid > c13bc007afe382f898b3b1cfcaf62e82 > files > 783

allegro-devel-4.4.1.1-2ark.x86_64.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Allegro Manual: Loading image files
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" title="Default" type="text/css" href="allegro.css"></head><body bgcolor=white text=black link="#0000ee" alink="#ff0000" vlink="#551a8b">
<h1><a name="Loading image files">Loading image files</a></h1>

<ul>
<li><a href="#get_color_conversion">get_color_conversion</a> &mdash; Returns the current color conversion mode.
<li><a href="#load_bitmap">load_bitmap</a> &mdash; Loads any supported bitmap from a file.
<li><a href="#load_bmp">load_bmp</a> &mdash; Loads a BMP bitmap from a file.
<li><a href="#load_bmp_pf">load_bmp_pf</a> &mdash; Packfile version of load_bmp.
<li><a href="#load_lbm">load_lbm</a> &mdash; Loads an LBM bitmap from a file.
<li><a href="#load_pcx">load_pcx</a> &mdash; Loads a PCX bitmap from a file.
<li><a href="#load_pcx_pf">load_pcx_pf</a> &mdash; Packfile version of load_pcx.
<li><a href="#load_tga">load_tga</a> &mdash; Loads a TGA bitmap from a file.
<li><a href="#load_tga_pf">load_tga_pf</a> &mdash; Packfile version of load_tga.
<li><a href="#register_bitmap_file_type">register_bitmap_file_type</a> &mdash; Registers custom bitmap loading/saving functions.
<li><a href="#save_bitmap">save_bitmap</a> &mdash; Saves a bitmap into any supported file format.
<li><a href="#save_bmp">save_bmp</a> &mdash; Saves a bitmap into a BMP file.
<li><a href="#save_bmp_pf">save_bmp_pf</a> &mdash; Packfile version of save_bmp.
<li><a href="#save_pcx">save_pcx</a> &mdash; Saves a bitmap into a PCX file.
<li><a href="#save_pcx_pf">save_pcx_pf</a> &mdash; Packfile version of save_pcx.
<li><a href="#save_tga">save_tga</a> &mdash; Saves a bitmap into a TGA file.
<li><a href="#save_tga_pf">save_tga_pf</a> &mdash; Packfile version of save_tga.
<li><a href="#set_color_conversion">set_color_conversion</a> &mdash; Tells Allegro how to convert images during loading time.
</ul>

<p>
Warning: when using truecolor images, you should always set the graphics
mode before loading any bitmap data! Otherwise the pixel format (RGB or BGR)
will not be known, so the file may be converted wrongly.

<p><br>
<div class="al-api"><b><a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *<a name="load_bitmap">load_bitmap</a>(const char *filename, <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   Loads a bitmap from a file. The palette data will be stored in the second
   parameter, which should be an array of 256 RGB structures. At present this
   function supports BMP, LBM, PCX, and TGA files, determining the type from
   the file extension.

<p>
   If the file contains a truecolor image, you must set the video mode or
   call set_color_conversion() before loading it. In this case, if the
   destination color depth is 8-bit, the palette will be generated by calling
   generate_optimized_palette() on the bitmap; otherwise, the returned
   palette will be generated by calling generate_332_palette().

<p>
   The pal argument may be NULL. In this case, the palette data are simply
   not returned. Additionally, if the file is a truecolor image and the
   destination color depth is 8-bit, the color conversion process will use
   the current palette instead of generating an optimized one.

<p>
   Example:
<blockquote class="code"><pre>
      <a href="alleg001.html#BITMAP" class="autotype" title="Stores the contents of a bitmap.">BITMAP</a> *bmp;
      <a href="alleg001.html#PALETTE" class="autotype" title="Stores palette information.">PALETTE</a> palette;
      ...
      bmp = <a href="#load_bitmap" class="autotype" title="Loads any supported bitmap from a file.">load_bitmap</a>("image.pcx", palette);
      if (!bmp)
         abort_on_error("Couldn't load image.pcx!");
      ...
      <a href="alleg009.html#destroy_bitmap" class="autotype" title="Destroys any type of created bitmap.">destroy_bitmap</a>(bmp);</pre></blockquote>
<p><b>Return value:</b>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_bmp" title="Loads a BMP bitmap from a file.">load_bmp</a>,
<a class="xref" href="#load_lbm" title="Loads an LBM bitmap from a file.">load_lbm</a>,
<a class="xref" href="#load_pcx" title="Loads a PCX bitmap from a file.">load_pcx</a>,
<a class="xref" href="#load_tga" title="Loads a TGA bitmap from a file.">load_tga</a>,
<a class="xref" href="alleg009.html#destroy_bitmap" title="Destroys any type of created bitmap.">destroy_bitmap</a>,
<a class="xref" href="#save_bitmap" title="Saves a bitmap into any supported file format.">save_bitmap</a>,
<a class="xref" href="#register_bitmap_file_type" title="Registers custom bitmap loading/saving functions.">register_bitmap_file_type</a>,
<a class="xref" href="alleg008.html#set_color_depth" title="Sets the global pixel color depth.">set_color_depth</a>,
<a class="xref" href="#set_color_conversion" title="Tells Allegro how to convert images during loading time.">set_color_conversion</a>,
<a class="xref" href="alleg011.html#generate_optimized_palette" title="Generates an optimized palette for a bitmap.">generate_optimized_palette</a>,
<a class="xref" href="alleg011.html#generate_332_palette" title="Constructs a fake truecolor palette.">generate_332_palette</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#Available Allegro examples" title="">Available Allegro examples</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *<a name="load_bmp">load_bmp</a>(const char *filename, <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   Loads an 8-bit, 16-bit, 24-bit or 32-bit Windows or OS/2 BMP file.
<p><b>Return value:</b>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_bitmap" title="Loads any supported bitmap from a file.">load_bitmap</a>,
<a class="xref" href="#load_bmp_pf" title="Packfile version of load_bmp.">load_bmp_pf</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *<a name="load_bmp_pf">load_bmp_pf</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f, <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   A version of load_bmp() which reads from a packfile. Example:
<blockquote class="code"><pre>
      <a href="alleg001.html#PACKFILE" class="autotype" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *packfile;
      <a href="alleg001.html#BITMAP" class="autotype" title="Stores the contents of a bitmap.">BITMAP</a> *bmp;

      packfile = <a href="alleg030.html#pack_fopen" class="autotype" title="Opens a file according to mode.">pack_fopen</a>("mybitmap.bmp", F_READ);
      if (!packfile)
         abort_on_error("Couldn't open mybitmap.bmp");
         
      bmp = <a href="#load_bmp_pf" class="autotype" title="Packfile version of load_bmp.">load_bmp_pf</a>(packfile, pal);
      if (!bmp)
         abort_on_error("Error loading mybitmap.bmp");</pre></blockquote>
<p><b>Return value:</b>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_bmp" title="Loads a BMP bitmap from a file.">load_bmp</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *<a name="load_lbm">load_lbm</a>(const char *filename, <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   Loads a 256-color IFF ILBM/PBM file.
<p><b>Return value:</b>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_bitmap" title="Loads any supported bitmap from a file.">load_bitmap</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *<a name="load_pcx">load_pcx</a>(const char *filename, <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   Loads a 256-color or 24-bit truecolor PCX file.
<p><b>Return value:</b>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_bitmap" title="Loads any supported bitmap from a file.">load_bitmap</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>,
<a class="eref" href="alleg045.html#exscale" title="Loading PCX files and bitmap stretching.">exscale</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *<a name="load_pcx_pf">load_pcx_pf</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f, <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   A version of load_pcx() which reads from a packfile. Example:
<blockquote class="code"><pre>
      <a href="alleg001.html#PACKFILE" class="autotype" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *packfile;
      <a href="alleg001.html#BITMAP" class="autotype" title="Stores the contents of a bitmap.">BITMAP</a> *bmp;

      packfile = <a href="alleg030.html#pack_fopen" class="autotype" title="Opens a file according to mode.">pack_fopen</a>("mybitmap.pcx", F_READ);
      if (!packfile)
         abort_on_error("Couldn't open mybitmap.pcx");
         
      bmp = <a href="#load_bmp_pf" class="autotype" title="Packfile version of load_bmp.">load_bmp_pf</a>(packfile, pal);
      if (!bmp)
         abort_on_error("Error loading mybitmap.pcx");</pre></blockquote>
<p><b>Return value:</b>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_pcx" title="Loads a PCX bitmap from a file.">load_pcx</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *<a name="load_tga">load_tga</a>(const char *filename, <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   Loads a 256-color, 15-bit hicolor, 24-bit truecolor, or 32-bit 
   truecolor+alpha TGA file.
<p><b>Return value:</b>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_bitmap" title="Loads any supported bitmap from a file.">load_bitmap</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *<a name="load_tga_pf">load_tga_pf</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f, <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   A version of load_tga() which reads from a packfile. Example:
<blockquote class="code"><pre>
      <a href="alleg001.html#PACKFILE" class="autotype" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *packfile;
      <a href="alleg001.html#BITMAP" class="autotype" title="Stores the contents of a bitmap.">BITMAP</a> *bmp;

      packfile = <a href="alleg030.html#pack_fopen" class="autotype" title="Opens a file according to mode.">pack_fopen</a>("mybitmap.tga", F_READ);
      if (!packfile)
         abort_on_error("Couldn't open mybitmap.tga");
         
      bmp = <a href="#load_bmp_pf" class="autotype" title="Packfile version of load_bmp.">load_bmp_pf</a>(packfile, pal);
      if (!bmp)
         abort_on_error("Error loading mybitmap.tga");</pre></blockquote>
<p><b>Return value:</b>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_tga" title="Loads a TGA bitmap from a file.">load_tga</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>.</blockquote>
<div class="al-api"><b>int <a name="save_bitmap">save_bitmap</a>(const char *filename, <a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   Writes a bitmap into a file, using the specified palette, which should be 
   an array of 256 RGB structures. The output format is determined from the
   filename extension: at present this function supports BMP, PCX and TGA
   formats.

<p>
   Two things to watch out for: on some video cards it may be faster to copy
   the screen to a memory bitmap and save the latter, and if you use this to
   dump the screen into a file you may end up with an image much larger than
   you were expecting, because Allegro often creates virtual screens larger
   than the visible screen. You can get around this by using a sub-bitmap to
   specify which part of the screen to save, eg:
<blockquote class="code"><pre>
      <a href="alleg001.html#BITMAP" class="autotype" title="Stores the contents of a bitmap.">BITMAP</a> *bmp;
      <a href="alleg001.html#PALETTE" class="autotype" title="Stores palette information.">PALETTE</a> pal;
      ...
      <a href="alleg011.html#get_palette" class="autotype" title="Retrieves the entire palette of 256 colors.">get_palette</a>(pal);
      bmp = <a href="alleg009.html#create_sub_bitmap" class="autotype" title="Creates a memory sub bitmap.">create_sub_bitmap</a>(<a href="alleg009.html#screen" class="autotype" title="Global pointer to the screen hardware video memory.">screen</a>, 0, 0, <a href="alleg009.html#SCREEN_W" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_W</a>, <a href="alleg009.html#SCREEN_H" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_H</a>);
      <a href="#save_bitmap" class="autotype" title="Saves a bitmap into any supported file format.">save_bitmap</a>("dump.pcx", bmp, pal);
      <a href="alleg009.html#destroy_bitmap" class="autotype" title="Destroys any type of created bitmap.">destroy_bitmap</a>(bmp);</pre></blockquote>
<p><b>Return value:</b>
   Returns non-zero on error.
      

<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#save_bmp" title="Saves a bitmap into a BMP file.">save_bmp</a>,
<a class="xref" href="#save_pcx" title="Saves a bitmap into a PCX file.">save_pcx</a>,
<a class="xref" href="#save_tga" title="Saves a bitmap into a TGA file.">save_tga</a>,
<a class="xref" href="#load_bitmap" title="Loads any supported bitmap from a file.">load_bitmap</a>,
<a class="xref" href="#register_bitmap_file_type" title="Registers custom bitmap loading/saving functions.">register_bitmap_file_type</a>.</blockquote>
<div class="al-api"><b>int <a name="save_bmp">save_bmp</a>(const char *filename, <a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   Writes a bitmap into a 256-color or 24-bit truecolor BMP file.
<p><b>Return value:</b>
   Returns non-zero on error.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#save_bitmap" title="Saves a bitmap into any supported file format.">save_bitmap</a>.</blockquote>
<div class="al-api"><b>int <a name="save_bmp_pf">save_bmp_pf</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f, <a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   A version of save_bmp which writes to a packfile.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#save_bmp" title="Saves a bitmap into a BMP file.">save_bmp</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>.</blockquote>
<div class="al-api"><b>int <a name="save_pcx">save_pcx</a>(const char *filename, <a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   Writes a bitmap into a 256-color or 24-bit truecolor PCX file.
<p><b>Return value:</b>
   Returns non-zero on error.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#save_bitmap" title="Saves a bitmap into any supported file format.">save_bitmap</a>.</blockquote>
<div class="al-api"><b>int <a name="save_pcx_pf">save_pcx_pf</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f, <a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   A version of save_pcx which writes to a packfile.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#save_pcx" title="Saves a bitmap into a PCX file.">save_pcx</a>.</blockquote>
<div class="al-api"><b>int <a name="save_tga">save_tga</a>(const char *filename, <a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   Writes a bitmap into a 256-color, 15-bit hicolor, 24-bit truecolor, or
   32-bit truecolor+alpha TGA file.
<p><b>Return value:</b>
   Returns non-zero on error.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#save_bitmap" title="Saves a bitmap into any supported file format.">save_bitmap</a>.</blockquote>
<div class="al-api"><b>int <a name="save_tga_pf">save_tga_pf</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f, <a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal);</b></div><br>
   A version of save_tga which writes to a packfile.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#save_tga" title="Saves a bitmap into a TGA file.">save_tga</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>.</blockquote>
<div class="al-api"><b>void <a name="register_bitmap_file_type">register_bitmap_file_type</a>(const char *ext,
          <a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *(*load)(const char *filename, <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal),
          int (*save)(const char *filename, <a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const <a class="autotype" href="alleg001.html#RGB" title="Single palette entry.">RGB</a> *pal));</b></div><br>
   Informs the load_bitmap() and save_bitmap() functions of a new file type, 
   providing routines to read and write images in this format (either 
   function may be NULL). The functions you supply must follow the same
   prototype as load_bitmap() and save_bitmap(). Example:
<blockquote class="code"><pre>
      <a href="alleg001.html#BITMAP" class="autotype" title="Stores the contents of a bitmap.">BITMAP</a> *load_dump(const char *filename, <a href="alleg001.html#RGB" class="autotype" title="Single palette entry.">RGB</a> *pal)
      {
         ...
      }
      
      int save_dump(const char *filename, <a href="alleg001.html#BITMAP" class="autotype" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const <a href="alleg001.html#RGB" class="autotype" title="Single palette entry.">RGB</a> *pal)
      {
         ...
      }

         <a href="#register_bitmap_file_type" class="autotype" title="Registers custom bitmap loading/saving functions.">register_bitmap_file_type</a>("dump", load_dump, save_dump);</pre></blockquote>


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_bitmap" title="Loads any supported bitmap from a file.">load_bitmap</a>,
<a class="xref" href="#save_bitmap" title="Saves a bitmap into any supported file format.">save_bitmap</a>.</blockquote>
<div class="al-api"><b>void <a name="set_color_conversion">set_color_conversion</a>(int mode);</b></div><br>
   Specifies how to convert images between the various color depths when 
   reading graphics from external bitmap files or datafiles. The mode is a 
   bitmask specifying which types of conversion are allowed. If the 
   appropriate bit is set, data will be converted into the current pixel 
   format (selected by calling the set_color_depth() function), otherwise it 
   will be left in the same format as the disk file, leaving you to convert 
   it manually before the graphic can be displayed. The default mode is 
   total conversion, so that all images will be loaded in the appropriate
   format for the current video mode. Valid bit flags are:
<blockquote class="text"><pre>
      COLORCONV_NONE                // disable all format
                                    // conversions
      COLORCONV_8_TO_15             // expand 8-bit to 15-bit
      COLORCONV_8_TO_16             // expand 8-bit to 16-bit
      COLORCONV_8_TO_24             // expand 8-bit to 24-bit
      COLORCONV_8_TO_32             // expand 8-bit to 32-bit
      COLORCONV_15_TO_8             // reduce 15-bit to 8-bit
      COLORCONV_15_TO_16            // expand 15-bit to 16-bit
      COLORCONV_15_TO_24            // expand 15-bit to 24-bit
      COLORCONV_15_TO_32            // expand 15-bit to 32-bit
      COLORCONV_16_TO_8             // reduce 16-bit to 8-bit
      COLORCONV_16_TO_15            // reduce 16-bit to 15-bit
      COLORCONV_16_TO_24            // expand 16-bit to 24-bit
      COLORCONV_16_TO_32            // expand 16-bit to 32-bit
      COLORCONV_24_TO_8             // reduce 24-bit to 8-bit
      COLORCONV_24_TO_15            // reduce 24-bit to 15-bit
      COLORCONV_24_TO_16            // reduce 24-bit to 16-bit
      COLORCONV_24_TO_32            // expand 24-bit to 32-bit
      COLORCONV_32_TO_8             // reduce 32-bit RGB to 8-bit
      COLORCONV_32_TO_15            // reduce 32-bit RGB to 15-bit
      COLORCONV_32_TO_16            // reduce 32-bit RGB to 16-bit
      COLORCONV_32_TO_24            // reduce 32-bit RGB to 24-bit
      COLORCONV_32A_TO_8            // reduce 32-bit RGBA to 8-bit
      COLORCONV_32A_TO_15           // reduce 32-bit RGBA to 15-bit
      COLORCONV_32A_TO_16           // reduce 32-bit RGBA to 16-bit
      COLORCONV_32A_TO_24           // reduce 32-bit RGBA to 24-bit
      COLORCONV_DITHER_PAL          // dither when reducing to 8-bit
      COLORCONV_DITHER_HI           // dither when reducing to
                                    // hicolor
      COLORCONV_KEEP_TRANS          // keep original transparency
</pre></blockquote>
   For convenience, the following macros can be used to select common 
   combinations of these flags:
<blockquote class="text"><pre>
      COLORCONV_EXPAND_256          // expand 256-color to hi/truecolor
      COLORCONV_REDUCE_TO_256       // reduce hi/truecolor to 256-color
      COLORCONV_EXPAND_15_TO_16     // expand 15-bit hicolor to 16-bit
      COLORCONV_REDUCE_16_TO_15     // reduce 16-bit hicolor to 15-bit
      COLORCONV_EXPAND_HI_TO_TRUE   // expand 15/16-bit to 24/32-bit
      COLORCONV_REDUCE_TRUE_TO_HI   // reduce 24/32-bit to 15/16-bit
      COLORCONV_24_EQUALS_32        // convert between 24- and 32-bit
      COLORCONV_TOTAL               // everything to current format
      COLORCONV_PARTIAL             // convert 15 &lt;-&gt; 16-bit and
                                    // 24 &lt;-&gt; 32-bit
      COLORCONV_MOST                // all but hi/truecolor &lt;-&gt; 256
      COLORCONV_DITHER              // dither during all color reductions
      COLORCONV_KEEP_ALPHA          // convert everything to current format
                                    // unless it would lose alpha information
</pre></blockquote>
   If you enable the COLORCONV_DITHER flag, dithering will be performed 
   whenever truecolor graphics are converted into a hicolor or paletted 
   format, including by the blit() function, and any automatic conversions 
   that take place while reading graphics from disk. This can produce much 
   better looking results, but is obviously slower than a direct conversion.

<p>
   If you intend using converted bitmaps with functions like masked_blit() 
   or draw_sprite(), you should specify the COLORCONV_KEEP_TRANS flag. It 
   will ensure that the masked areas in the bitmap before and after the 
   conversion stay exactly the same, by mapping transparent colors to each 
   other and adjusting colors which would be converted to the transparent 
   color otherwise. It affects every blit() operation between distinct pixel 
   formats and every automatic conversion.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="alleg008.html#set_color_depth" title="Sets the global pixel color depth.">set_color_depth</a>,
<a class="xref" href="#load_bitmap" title="Loads any supported bitmap from a file.">load_bitmap</a>,
<a class="xref" href="alleg031.html#load_datafile" title="Loads a datafile into memory.">load_datafile</a>,
<a class="xref" href="alleg031.html#fixup_datafile" title="Fixes truecolor images in compiled datafiles.">fixup_datafile</a>,
<a class="xref" href="alleg012.html#makecol15_dither" title="Calculates a dithered 15 or 16-bit RGB value.">makecol15_dither</a>,
<a class="xref" href="#get_color_conversion" title="Returns the current color conversion mode.">get_color_conversion</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exalpha" title="Creating and using 32 bit RGBA sprites.">exalpha</a>,
<a class="eref" href="alleg045.html#exblend" title="Using translucency in truecolor modes.">exblend</a>,
<a class="eref" href="alleg045.html#exdata" title="Accessing the contents of datafiles.">exdata</a>,
<a class="eref" href="alleg045.html#exexedat" title="Appending datafiles onto your executable.">exexedat</a>,
<a class="eref" href="alleg045.html#exlights" title="One way to do colored lighting effects in a hicolor video mode.">exlights</a>,
<a class="eref" href="alleg045.html#exrotscl" title="Demonstrates rotate_scaled_sprite functions.">exrotscl</a>,
<a class="eref" href="alleg045.html#exxfade" title="Truecolor image loading and fades.">exxfade</a>.</blockquote>
<div class="al-api"><b>int <a name="get_color_conversion">get_color_conversion</a>();</b></div><br>
   Returns the current color conversion mode.




<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_color_conversion" title="Tells Allegro how to convert images during loading time.">set_color_conversion</a>.</blockquote>
<hr><div class="al-back-to-contents"><a href="allegro.html">Back to contents</a></div>

</body>
</html>