galfar.imaginglib/Doc/VampyreDoc/Procedures/Low/Loading.xml

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="../../Xsl/doc2html.xsl"?>
<doc>
  <title>Loading Images</title>
  <chapter>
    <title>Loading Images</title>
    <par>
      Images can be loaded from the files on disk, from the streams or
      from a memory referenced by a pointer.
      The following table lists functions for loading images. These are low level
      functions operating on <ref>TImageData</ref> structure.
    </par>

    <table>
      <row>
        <header>Function name</header>
        <header>Usage</header>
      </row>
      <row>
        <cell><ref>LoadImageFromFile</ref></cell>
        <cell>Load single image from file</cell>
      </row>
      <row>
        <cell><ref>LoadImageFromStream</ref></cell>
        <cell>Load single image from stream
        (<icode>TStream</icode> descendants, <b>Object Pascal only</b>)</cell>
      </row>
      <row>
        <cell><ref>LoadImageFromMemory</ref></cell>
        <cell>Load single image from memory</cell>
      </row>
      <row>
        <cell><ref>LoadMultiImageFromFile</ref></cell>
        <cell>Load multiple images from file</cell>
      </row>
      <row>
        <cell><ref>LoadMultiImageFromStream</ref></cell>
        <cell>Load multiple images from stream
        (<icode>TStream</icode> descendants, <b>Object Pascal only</b>)</cell>
      </row>
      <row>
        <cell><ref>LoadMultiImageFromMemory</ref></cell>
        <cell>Load multiple images from memory</cell>
      </row>
    </table>

    <par>
      If you want to make sure that image in file is really in format
      suggested by its extension or if you have some unknown images
      in stream or memory, you can use these functions to get
      their file format:
    </par>
    
    <table>
      <row>
        <header>Function name</header>
        <header>Usage</header>
      </row>
      <row>
        <cell><ref>DetermineFileFormat</ref></cell>
        <cell>Determines format of image specified by its file name</cell>
      </row>
      <row>
        <cell><ref>DetermineStreamFormat</ref></cell>
        <cell>Determines format of image located in stream 
        (<icode>TStream</icode> descendants, <b>Object Pascal only</b>)</cell>
      </row>
      <row>
        <cell><ref>DetermineMemoryFormat</ref></cell>
        <cell>Determines format of image located in memory</cell>
      </row>
    </table>  

    <par>
      This example loads image from file and prints its width, height and
      size of memory it occupies.
    </par>
    <code>
uses
  SysUtils, Classes, ImagingTypes, Imaging;
var
  Img: <ref>TImageData</ref>;
begin
  // call this before using any TImageData record
  <ref>InitImage</ref>(Img);
  // load tigers from file
  <ref>LoadImageFromFile</ref>('X:\images\tigers.jpg', Img);
  //write some image info
  WriteLn('Mighty tigers have resolution ', Img.Width, 'x', Img.Height,
  ' and occupy ', Img.Size, ' bytes of your memory.');
  // memory occupied by image is freed
  <ref>FreeImage</ref>(Img);
end.
    </code>

    <par>
      This example shows how to load multiple images stored in one file
      (DDS texture in this case) located in the memory.
    </par>
    
    <code>
var
  Data: Pointer;
  Size: LongInt;
  Images: <ref>TDynImageDataArray</ref>;
  I: LongInt;
begin
  // Here you for example load DDS texture compressed by your new
  // compression algorithm from file and decompress it.
  // Decompressed image is now in memory referenced by Data and
  // size of this image is in Size variable.
  // Note that there is no need to call <ref>InitImage</ref> for <ref>TDynImageDataArray</ref>.
  <ref>LoadMultiImageFromMemory</ref>(Data, Size, Images);
  // write something
  WriteLn('DDS file contains ', Length(Image), 'subimages.');
  // You can then free images in array by calling <ref>FreeImage</ref> for all of them ...
  for I := 0 to Length(Images) - 1 do
    <ref>FreeImage</ref>(Images[I]);
  // ... or simply call <ref>FreeImagesInArray</ref> which does the same job
  <ref>FreeImagesInArray</ref>(Images);
end;
    </code>
    
    <par>
      This example shows how to load image from stream without knowing
      what format it is in.
    </par>

    <code>
function LoadImage(var Img: <ref>TImageData</ref>; Stream: TStream): Boolean;
var
  Ext: string;
begin
  // call this before using any TImageData record
  <ref>InitImage</ref>(Img);
  // determine image's format
  Ext := <ref>DetermineStreamFormat</ref>(Stream);
  // if image is in unsupported format or is invalid we output error
  if Ext = '' then
  begin
    WriteLn('Image in stream in unsupported formatus!');
    Result := False;
  end
  else
  begin
    // load image if its type is known
    Result := <ref>LoadImageFromStream</ref>(Stream, Img);
  end;
end;    
    </code>
    
  </chapter>
</doc>