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

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="../../Xsl/doc2html.xsl"?>
<doc>
  <title>Using dll/so Access</title>
  <chapter>
    <title>Using dll/so Access</title>
    <par>You can use Imaging library directly from your <b>Object Pascal</b>
    project by means of <icode>uses</icode> clause.
    This kind of usage is recommended but you can also use Imaging library
    in the form of external library - dynamic link library (Windows <keyword>
    dll</keyword> file) or shared objects (Linux <keyword>SO</keyword> file).
    Using external library can be useful if you have have more executables
    using Imaging which will be distributed together (so you can have
    smaller executables). This is also only way how to use Imaging from
    programming languages other than <b>Object Pascal</b>.</par>

    <par>First you need Imaging compiled to external library. Projects
    for building external library can be found in
    <keyword>Source/Projects</keyword> directory.
    You can also use build scripts named <keyword>BuildLibrary*.bat</keyword>
    and <keyword>BuildLibrary*.sh</keyword>. They are located in
    <keyword>Scripts</keyword> directory and compiled library will be placed
    in <keyword>Bin</keyword> directory. In order to successfully use
    these scripts you must have paths to compilers properly set.
    When you have compiled library you must assure that operating system is
    be able to find it at your application's startup.
    Windows library is named <keyword>VampyreImaging.dll</keyword> and
    Linux version has name <keyword>libVampyreImaging.so</keyword>.
    </par>

    <par>
    Next thing you need is wrapper for programming language you want to use.
    Now there are wrappers for <b>Object Pascal</b>, <b>C/C++</b>
    and <b>Delphi.NET</b>. Wrappers are located in
    <keyword>Source/Wrappers</keyword> directory.
    </par>

    <note>
    Some types of function parameters differ between dll/so usage and
    direct usage. <icode>string</icode> types are changed to <icode>PChar</icode>
    types, dynamic arrays are not used at all - wrapper type
    <ref>TImageDataList</ref> is used instead.
    Also all function names have <icode>Im</icode> prefix.
    </note>

    <par>
    Here you can find some code fragments which will show you how
    to use dll/so access to Imaging library.
    If you want samples in language other than <b>Object Pascal</b> look
    at <link url="../Demos/Demos.xml">Demos</link>.  
    </par>

    <code>
uses
  ImagingTypes, ImagingImport;
var
  Img: <ref>TImageData</ref>
begin
  // this call loads external Imaging library, you should check if it was successful
  if not <ref>ImLoadLibrary</ref> then
    WriteLn('Imaging library dll was not loaded successfully, program will crash soon!');
  // call this before any access to TImageData is made
  <ref>ImInitImage</ref>(Img);
  // load some image
  <ref>ImLoadImageFromFile</ref>('/home/galfar/images/jaguar.jpg', Img);
  // compress it to DXT1 format
  <ref>ImConvertImage</ref>(Img, ifDXT1);
  // and save it in DDS file format
  <ref>ImSaveImageToFile</ref>('/home/galfar/images/jaguar.dds', Img);
  // free memory occupied by image
  <ref>ImFreeImage</ref>(Img);
  // unload Imaging library
  <ref>ImFreeLibrary</ref>;
end.
    </code>

    <par>Since <ref>TDynImageDataArray</ref> is <b>Object Pascal</b> dynamic array,
    which can not be used from other languages, all parameters of this
    type are replaced with <ref>TImageDataList</ref> typed parameters.
    Some new functions are introduced for accessing list's items and properties.
    You can see them all in action in the next code listing.
    </par>

        <code>
uses
  ImagingTypes, ImagingImport;
var
  ImgList: <ref>TImageDataList</ref>;
  Img: <ref>TImageData</ref>;
  I, Size: LongInt;
begin
  // this call loads external Imaging library, you should check if it was successful
  if not <ref>ImLoadLibrary</ref> then
    WriteLn('Imaging library dll was not loaded successfully, program will crash soon!');
  // make sure list pointer doesn't point to invalid memory address
  ImgList := nil;
  // load some images, list's size is changed during loading
  <ref>ImLoadMultiImageFromFile</ref>('/home/galfar/images/jaguar_with_mipmaps.jpg', Img);
  // get the actual list's size
  Size := <ref>ImGetImageListSize</ref>(ImgList);
  for I := 0 to Size - 1 do
  begin
    // get list's element
    <ref>ImGetImageListElement</ref>(ImgList, Img, I);
    // resize element
    <ref>ImResizeImage</ref>(Img, Img.Width / 2, Img.Height / 2, rfBicubic);
    // set list's element
    <ref>ImSetImageListElement</ref>(ImgList, Img, I);
  end;
  // create space for new image in the list
  <ref>ImSetImageListSize</ref>(ImgList, Size + 1);
  // create new image
  <ref>ImNewImage</ref>(256, 256, ifDXT1, Img);
  // put this new image into the list
  <ref>ImSetImageListElement</ref>(ImgList, Img, Size);
  // save halved images to file
  <ref>ImSaveMultiImageToFile</ref>('/home/galfar/images/jaguar_smaller.dds', Img);
  // free all images in list and list itself
  <ref>ImFreeImageList</ref>(ImgList);
  // unload Imaging library
  <ref>ImFreeLibrary</ref>;
end.
    </code>
  </chapter>
</doc>