Free Image 3151

8/13/2019 Free Image 3151

1/129

FreeImage

a free, open sourcegraphics library

Documentation

Library version 3.15.1

8/13/2019 Free Image 3151

2/129

ContentsIntroduction 1

Foreword ...............................................................................................................................1

Purpose of FreeImage ........................................................................................................... 1

Library reference .......................................................................................................... ........ 2

itmap function reference 3

General functions ..................................................................................................................3

Bitmap management functions .................................................................................. .......... . 5Bitmap information functions ............................................................................................. 13

Filetype functions ........................................................................................................ ....... 23

Piel access functions ......................................................................................................... 25

!on"ersion functions ........................................................................................................ .. 31

#one mapping operators ..................................................................................................... 3$

I!! profile functions .......................................................................................................... %1

Plugin functions .................................................................................................................. %3

&ultipage functions ............................................................................................................ 51

&emory I'( streams ........................................................................................................... 5)

!ompression functions ............................................................................................... ........ **

+elper functions ......................................................................................................... ........ *,

!etadata function reference "#

Introduction ............................................................................................................ .......... .. )-

#ag creation and destruction .................................................................................... .......... )3

#ag accessors ......................................................................................................................)%

&etadata iterator .................................................................................................................))

&etadata accessors ....................................................................................................... ...... )$

&etadata elper functions .......................................................................................... ........ $-

$ool%it function reference &'

/otation and flipping .......................................................................................................... $2

0psampling ' downsampling ........................................................................................ ...... $*

!olor manipulation ............................................................................................................. $,!annel processing ............................................................................................................ .,5

!opy ' Paste ' !omposite routines ......................................................................................,*

Bacground filling ............................................................................................................ 1-1

&iscellaneous algoritms ............................................................................................ ..... 1-*

(ppendi) 1#"

upported file formats ................................................................................................... ... 1-)

upported camera /4 file formats .................................................................... ......... .. 1-$

!oosing te rigt resampling filter ........................................................................... ...... 1-,

0sing te rotation functions ..............................................................................................113

FreeImage metadata models ......................................................................................... .... 11*

FI&67II(7 metadata model specification ........................................ ........ ....... 12-

FreeImage 3.15.1 documentation Contents i

8/13/2019 Free Image 3151

3/129

List of tables

$able 1* F+-I!(-F/+!($0 constants FreeImage formatidentifiers2. 5

$able '* F+-I!(-$4 constants FreeImage data typeidentifiers2. "

$able 3* /ptionnal decoder constants. &

$able * /ptionnal encoder constants. 11

$able 5* F+-I!(-C/L/+-$4 constants. 16

$able 6* 4i)el access macros and associated mas%s for '7 or 3'7bitimages. '6

$able "* F+-I!(-89(:$I; constants. 3'

$able &* F+-I!(-DI$ed by FreeImage. 36

$able 1#* F+-I!(-$!/ constants. 3&

$able 11* FreeImage FI$( structure. "#

$able 1'* FreeImage tag data types F+-I!(-!D$4

identifier2. "1

$able 13* !etadata models supported by FreeImage. "'

$able 1* F+-I!(-?4-/4+($I/: constants. &5

$able 15* I!(-FIL$+ constants. &6

$able 16* F+-I!(-C/L/+-C

8/13/2019 Free Image 3151

4/129

$able 1=* List of tag %eys supported by the I4$C metadata model. 11&

List of figures

Figure 1* Illustration of the FreeImage-Composite function. =&

Figure '* Comparison of resampling filters on a 3')3' Lena imageresi@ed to ##A. 11#

Figure 3* Comparison of resampling filters on a #)6 i%ini imageresi@ed to #A. 11'

Figure * 4arrot image rotated by 5B using FreeImage-+otate. 113

Figure 5* 4arrot image rotated by =#B using FreeImage-+otate. 113

Figure 6* 0ome e)amples illustrating the use of FreeImage-+otate).11

FreeImage 3.15.1 documentation Contents iii

8/13/2019 Free Image 3151

5/129

Introduction

Fore>ord

Thank you for downloading FreeImage, a free and open source graphics library for Windows,Linux and Mac OS ! FreeImage is widely used and praised for i"s speed and simplici"y! I" hasbeen under de#elopmen" for more "han $$ years!

FreeImage was crea"ed by Floris #an den %erg! I" was originally de#eloped "o pro#ide bi"maploading suppor" "o an au"horing "ool named "he Magen"a Mul"imedia Tool! The ma&or par"s of"he library were designed by Floris, bu" in i"s long life"ime, many people ha#e con"ribu"ed "oFreeImage, adding new fea"ures and helping "o "es" "he library! Wi"hou" "he help of "hesepeople, FreeImage wouldn'" ha#e been where i" is now! (nyone can con"ribu"e and pos" "heirchanges and impro#emen"s and ha#e "hem inser"ed in "he main sources )of course on "hecondi"ion "ha" de#elopers agree on "ha" "he fixes are good*! The lis" of con"ribu"ors in "hechangelog file is only a small par" of all "he people "ha" e#ery day pro#ide us wi"h bug repor"s,sugges"ions, ideas and source code!

In "he middle of "he year ++, Floris s"opped "he de#elopmen" of "he library! Since "his da"e,"he FreeImage -ro&ec" con"inues "o be de#eloped and is main"ained by .er#/ 0rolon!

4urpose of FreeImage

( clear pic"ure abou" a pro&ec" is impor"an", because i" is "ha" pic"ure "ha" defines whichfea"ures are implemen"ed and which are no"!

FreeImage suppor"s1

Loading and sa#ing of as many bi"map "ypes as possible

2asy access "o bi"map componen"s, such as pale""es and da"a bi"s

3on#er"ing bi"map's bi" dep"hs from one "o ano"her

(ccessing pages in a bi"map when "here are mul"iple, such as in TIFF

%asic manipula"ion of bi"maps, such as ro"a"ion, flipping and resampling or poin"opera"ions such as brigh"ness and con"ras" ad&us"men"

(lpha composi"ing and alpha blending

FreeImage does no" suppor"1

(d#anced image processing opera"ions such as con#olu"ion and "ransforms

%i"map drawing

4ec"or graphics

FreeImage 3.15.1 documentation (ppendi) 1

8/13/2019 Free Image 3151

6/129

Library reference

2ach func"ion name in FreeImage s"ar"s wi"h 5FreeImage65, for ins"anceFreeImage6Load, FreeImage6Sa#e, FreeImage67nload !!!

( de"ailed descrip"ion of each func"ion suppor"ed by "he FreeImage library is gi#en in "he

%i"map func"ion reference, Me"ada"a func"ion reference and Toolki" func"ion referencechap"ers! For each en"ry, "he func"ion pro"o"ype is shown for 38399 and "he func"ionargumen"s and explana"ions are lis"ed!

Throughou" "hese chap"ers, you will see numbers in colored boxes a" "he "op of somefunc"ions! These numbers indica"e "he pixel dep"h of "he inpu" image "ha" "he func"ion canopera"e on!

This may be1

$:, ;:, +:bi" per pixel for standard bitmap)green boxes*,

$=:, ;+:, =;:, +x=;:bi" for other special image types )yellow boxes*!

If boxed numbers are no" displayed "he func"ion opera"ion is independen" of "he imagepixel dep"h )e!g! for load 8 sa#e and plugins func"ions*!

' (ppendi) FreeImage 3.15.1 documentation

8/13/2019 Free Image 3151

7/129

itmap function reference

eneral functions

The following func"ions don'" ha#e any"hing "o do wi"h "he bi"map suppor" pro#ided byFreeImage! They are in"ernal library managemen" func"ions! Tha" doesn'" mean "hey are no"impor"an"! Wi"hou" "hem you won'" be able "o load any bi"map a" all!

FreeImage-Initialise

DLL_API void DLL_CALLCONV FreeImage_Initialise(BOOL load_local_plugins_onlyFI_DFA!L"(FAL#$$%

Ini"ialises "he library! When "he load_local_plugins_only parame"er is T@72, FreeImage won'"make use of ex"ernal plugins!

When using "he FreeImage 0LL, "his func"ion is called automatically wi"h "heload6local6plugins6only parame"er se" "o F(LS2! When using FreeImage as as"a"ic linked library, you mus" call "his func"ion e)actly oncea" "he s"ar" of yourprogram!

FreeImage-DeInitialise

DLL_API void DLL_CALLCONV FreeImage_DeInitialise($%

0eini"ialises "he library!

When using "he FreeImage 0LL, "his func"ion is called automatically! When using

FreeImage as a s"a"ic linked library, you mus" call "his func"ion e)actly oncea" "heend of your program "o clean up alloca"ed resources in "he FreeImage library!

7nder Linux or under any Anix OS )i!e! under 7nix or MacOS*, you need "o callFreeImage6Ini"ialise a" "he beginning of your main func"ion and you need "o callFreeImage60eIni"ialise a" "he end of "his main func"ion )"his is no" needed whenusing FreeImage as a !SO*!


8/13/2019 Free Image 3151

8/129

FreeImage-etersion

DLL_API const c&ar 'DLL_CALLCONV FreeImage_etVersion($%

@e"urns a s"ring con"aining "he curren" #ersion of "he library!

FreeImage-etCopyright!essage

DLL_API const c&ar 'DLL_CALLCONV FreeImage_etCopyrig&t)essage($%

@e"urns a s"ring con"aining a s"andard copyrigh" message you can show in your program!

FreeImage-0et/utput!essage

DLL_API void DLL_CALLCONV FreeImage_#etOutput)essage(FreeImage_Output)essageFunction

om*$%

When a cer"ain bi"map canno" be loaded or sa#ed "here is usually an explana"ion for i"! Forexample a cer"ain bi"map forma" migh" no" be suppor"ed due "o pa"en" res"ric"ions, or "heremigh" be a known issue wi"h a cer"ain bi"map sub"ype! Whene#er some"hing fails inFreeImage in"ernally a log:s"ring is genera"ed, which can be cap"ured by an applica"ion dri#ingFreeImage! Bou use "he func"ion FreeImage6Se"Ou"pu"Message "o cap"ure "he log s"ring so"ha" you can show i" "o "he user of "he program!

+''FreeImage error &andler,param *i* Format + Plugin responsi-le *or t&e error,param message rror message

'+void FreeImagerror.andler(F/_I)A_FO/)A" *i*0 const c&ar 'message$ 1 print*(23n''' 2$%i*(*i* 45 FIF_!N6NO7N$ 1

print*(28s Format3n20 FreeImage_etFormatFromFIF(*i*$$% 9 print*(message$% print*(2 '''3n2$%9

++ In your main program :

FreeImage_#etOutput)essage(FreeImagerror.andler$%

The fif parame"er passed in "he callback firs" argumen" may be eCual "oFIF_UNKNOWNwhen an error "ha" is no" rela"ed "o a plugin is genera"ed! In "his case,calling FreeImage_GetFormatFromFIF(FIF_UNKNOWN) will re"urn D7LL!Ei#ing a D7LL #alue "o func"ions such as printf()G may crash your applica"ion so &us"be careful H

(ppendi) FreeImage 3.15.1 documentation

8/13/2019 Free Image 3151

9/129

itmap management functions

The bi"map managemen" func"ions in FreeImage are defini"ely "he mos" used ones! Theyallow you "o alloca"e new bi"maps, impor" bi"maps so "ha" "hey can be edi"ed in memory andexpor" bi"maps "o disc! (s you will see, "he FreeImage bi"map managemen" func"ions are #eryeasy "o use!

(l"hough FreeImage can handle more "han + bi"map "ypes, "here are only ; bi"map handlingfunc"ions! ( special parame"er, an enum named F@226IM(E26FO@M(T, is used "o specify"he bi"map forma" "ha" will be loaded or sa#ed! This enum is defined in "he header fileF@22IM(E2!.! The following F@226IM(E26FO@M(TS cons"an"s are curren"ly a#ailable1

FIF Description

FIF67DDOWD 7nknown forma" )returned value only, never use it as input value*

FIF6%M- Windows or OS8+ %i"map File )A!%M-*

FIF637T 0r! .alo )A!37T*FIF600S 0irec"0raw Surface )A!00S*

FIF62@ ILM Open2@ )A!2@*

FIF6F(E> @aw Fax forma" 33ITT E> )A!E>*

FIF6EIF Eraphics In"erchange Forma" )A!EIF*

FIF6.0@ .igh 0ynamic @ange )A!.0@*

FIF6I3O Windows Icon )A!I3O*

FIF6IFF (miga IFF )A!IFF, A!L%M*

FIF6J+ J-2E:+ codes"ream )A!J+, A!J+3*

FIF6JDE J-2E De"work Eraphics )A!JDE*

FIF6J-+ J-2E:+ File Forma" )A!J-+*

FIF6J-2E Independen" J-2E Eroup )A!J-E, A!JIF, A!J-2E, A!J-2*FIF6O(L( 3ommodore =; oala forma" )A!O(*

FIF6MDE Mul"iple De"work Eraphics )A!MDE*

FIF6-%M -or"able %i"map )(S3II* )A!-%M*

FIF6-%M@(W -or"able %i"map )%ID(@B* )A!-%M*

FIF6-30 odak -ho"o30 )A!-30*

FIF6-3 Ksof" -ain"brush -3 bi"map forma" )A!-3*

FIF6-FM -or"able Floa"map )A!-FM*

FIF6-EM -or"able Eraymap )(S3II* )A!-EM*

FIF6-EM@(W -or"able Eraymap )%ID(@B* )A!-EM*

FIF6-I3T Macin"osh -I3T )A!-3T, A!-I3T, A!-I3*

FIF6-DE -or"able De"work Eraphics )A!-DE*

FIF6--M -or"able -ixelmap )(S3II* )A!--M*

FIF6--M@(W -or"able -ixelmap )%ID(@B* )A!--M*

FIF6-S0 (dobe -ho"oshop )A!-S0*

FIF6@(S Sun @as"erfile )A!@(S*

FIF6@(W @(W camera image )many extensions*

FIF6SEI Silicon Eraphics SEI image forma" )A!SEI*

FIF6T(@E( True#ision Targa files )A!TE(, A!T(@E(*

FIF6TIFF Tagged Image File Forma" )A!TIF, A!TIFF*

FIF6W%M- Wireless %i"map )A!W%M-*

FIF6%M $$ %i"map Forma" )A!%M*

FIF6-M $$ -ixmap Forma" )A!-M*

$able 1* F+-I!(-F/+!($0 constants FreeImage format identifiers2.


8/13/2019 Free Image 3151

10/129

(s an ex"ension "o "he F@226IM(E26FO@M(Ts, you can regis"er your own bi"map forma"s!@egis"ering bi"maps can be done manually, by calling one of "he plugin managemen"func"ions )see -lugin func"ions*, or au"oma"ically by copying a precompiled FreeImage bi"mapplugin 0LL in"o "he same direc"ory where F@22IM(E2!0LL is residing! When a new bi"map"ype is regis"ered i" is assigned a new, uniCue plugin iden"ifica"ion number "ha" you can pass"o "he same place "ha" you would pass a F@226IM(E26FO@M(T!

FreeImage-(llocate$ ; < $= +; >+

DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Allocate(int ;idt&0 int &eig&t0 int -pp0unsigned red_mas< FI_DFA!L"(=$0 unsigned green_mas< FI_DFA!L"(=$0 unsigned -lue_mas+ (rray of unsigned long1 unsigned >+:bi"

FIT6IDT>+ (rray of long1 signed >+:bi"

FIT6FLO(T (rray of floa"1 >+:bi" I222 floa"ing poin"

FIT60O7%L2 (rray of double1 =;:bi" I222 floa"ing poin"

FIT63OM-L2 (rray of FI3OM-L21 + x =;:bi" I222 floa"ing poin"

FIT6@E%$= ; x >+:bi" I222 floa"ing poin"

FIT6@E%(F $++:bi" I222 floa"ing poin"

$able '* F+-I!(-$4 constants FreeImage data type identifiers2.

When you need "o know "he da"a "ype of a bi"map, you can use "heFreeImage6Ee"ImageType func"ion!

FIBI")AP '-itmap 5 FreeImage_Allocate"(FI"_/B0 E?0 E?$%

i* (-itmap$ 1 ++ -itmap success*ully created4

FreeImage_!nload(-itmap$%9

FreeImage-Load

DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Load(F/_I)A_FO/)A" *i*0 const c&ar'*ilename0 int *lags FI_DFA!L"(=$$%

This func"ion decodes a bi"map, alloca"es memory for i" and "hen re"urns i" as a FI%ITM(-!The firs" parame"er defines "he "ype of bi"map "o be loaded! For example, when FIF6%M- ispassed, a %M- file is loaded in"o memory )an o#er#iew of possible F@226IM(E26FO@M(Tcons"an"s is a#ailable in Table $*! The second parame"er "ells FreeImage "he file i" has "odecode! The las" parame"er is used "o change "he beha#iour or enable a fea"ure in "he bi"map

plugin! 2ach plugin has i"s own se" of parame"ers!

FIBI")AP '-itmap 5 FreeImage_Load(FIF_B)P0 my-itmapG-mpH0 B)P_DFA!L"$%

i* (-itmap$ 1 ++ -itmap success*ully loaded4

FreeImage_!nload(-itmap$%9

Some bi"map loaders can recei#e parame"ers "o change "he loading beha#iour! When "heparame"er is no" a#ailable or unused you can pass "he #alue orNTB-26OF6%ITM(-602F(7LT )e!g! %M-602F(7LT, I3O602F(7LT, e"c*!

FreeImage 3.15.1 documentation (ppendi) "

8/13/2019 Free Image 3151

12/129

itmap type Flag Description

Nany type FIF6LO(06DO-I2LS When "his flag is suppor"ed by a plugin, load only header da"aand possibly me"ada"a )including embedded "humbnail*)$*

EIF EIF602F(7LT

EIF6LO(0+P= Load "he image as a +P= color image wi"h unused pale""een"ries, if i"Qs $= or + color

EIF6-L(B%(3 Q-layQ "he EIF "o genera"e each frame )as >+bpp* ins"ead ofre"urning raw frame da"a when loading

I3O I3O6M(2(L-.( 3on#er" "o >+:bi" and crea"e an alpha channel from "he (D0:mask when loading

J-2E J-2E602F(7LT Load "he file as fas" as possible, sacrificing some Cuali"y

J-2E6F(ST Load "he file as fas" as possible, sacrificing some Cuali"y

J-2E6(337@(T2 Load "he f ile wi"h "he bes" Cuali"y, sacrificing some speed

J-2E63MB This flag will load 3MB bi"maps as >+:bi" separa"ed 3MB)use R "o combine wi"h o"her load flags*

In"eger such "ha" flags

flags R ) NN $=*

Load and resie "he file such "ha" sie8 max)wid"h, heigh"*8

will re"urn an image scaled by +, ; or < )i!e! "he mos"appropria"e reCues"ed sie*! )+*

J-2E62IF@OT(T2 Load and ro"a"e according "o 2xif QOrien"a"ionQ "ag if a#ailable

-30 -30602F(7LT ( -ho"o30 pic"ure comes in many sies! This flag will load "heone sied =< x P$+

-306%(S2 This flag will load "he one sied =< x P$+

-306%(S20I4; This flag will load "he bi"map sied >

8/13/2019 Free Image 3151

13/129

This func"ion works exac"ly likeFreeImage6Load bu" suppor"s 7DI3O02 filenames! Do"e "ha""his func"ion only works on MS Windows opera"ing sys"ems! On o"her sys"ems, "he func"iondoes no"hing and re"urns D7LL!

FreeImage-LoadFrom

8/13/2019 Free Image 3151

14/129

++ t&is code assumes t&ere is a -itmap loaded and++ present in a varia-le called J-itmapK

i* (FreeImage_#ave(FIF_B)P0 -itmap0 my-itmapG-mpH0 =$$ 1 ++ -itmap success*ully saved49

Some bi"map sa#ers can recei#e parame"ers "o change "he sa#ing beha#iour! When "heparame"er is no" a#ailable or unused you can pass "he #alue orNTB-26OF6%ITM(-602F(7LT )e!g! %M-602F(7LT, I3O602F(7LT, e"c*!


%M- %M-602F(7LT Sa#e wi"hou" any compression

%M-6S(426@L2 3ompress "he bi"map using @L2 when sa#ing

2@ 2@602F(7LT Sa#e da"a as half wi"h pi:based wa#ele" compression

2@6FLO(TSa#e da"a as floa" ins"ead of as half )no"recommended*

2@6DOD2 Sa#e wi"h no compression

2@6KI- Sa#e wi"h lib compression, in blocks of $= scan lines

2@6-IK Sa#e wi"h pi:based wa#ele" compression

2@6-@+; Sa#e wi"h lossy +;:bi" floa" compression

2@6%;;Sa#e wi"h lossy ;; floa" compression : goes "o ++when combined wi"h 2@6L3

2@6L3Sa#e images wi"h one luminance and "wo chromachannels, ra"her "han as @E% )lossy compression*

J+ J+602F(7LT Sa#e wi"h a $=1$ ra"e

In"eger in U$!!P$+V Sa#e wi"h a 1$ ra"e

J-+ J-+602F(7LT Sa#e wi"h a $=1$ ra"e

In"eger in U$!!P$+V Sa#e wi"h a 1$ ra"e

J-2E J-2E602F(7LT Sa#es wi"h good Cuali"y )P1$*

J-2E6X7(LITBS7-2@% Sa#es wi"h superb Cuali"y )$1$*

J-2E6X7(LITBEOO0 Sa#es wi"h good Cuali"y )P1$*

J-2E6X7(LITBDO@M(L Sa#es wi"h normal Cuali"y )P1$*

J-2E6X7(LITB(42@(E2 Sa#es wi"h a#erage Cuali"y )+P1$*

J-2E6X7(LITB%(0 Sa#es wi"h bad Cuali"y )$1$*

In"eger in U!!$V Sa#e wi"h Cuali"y 1$

J-2E6-@OE@2SSI42Sa#es as a progressi#e J-2E file )use R "o combinewi"h J-2E Cuali"y flags*

J-2E6S7%S(M-LIDE6;$$ Sa#e wi"h high ;x$ chroma subsampling );1$1$*

J-2E6S7%S(M-LIDE6;+Sa#e wi"h medium +x+ chroma subsampling );1+1* :defaul" #alue

J-2E6S7%S(M-LIDE6;++ Sa#e wi"h low +x$ chroma subsampling );1+1+*

J-2E6S7%S(M-LIDE6;;; Sa#e wi"h no chroma subsampling );1;1;*

J-2E6O-TIMIK2On sa#ing, compu"e op"imal .uffman coding "ables)can reduce a few percen" of file sie*

J-2E6%(S2LID2Sa#e basic J-2E, wi"hou" me"ada"a or any markers)use R "o combine wi"h o"her J-2E flags*

-DE -DE602F(7LT Sa#e wi"h KLib le#el = compression and no in"erlacing

-DE6K6%2ST6S-220Sa#e using KLib le#el $ compression )defaul" #alue is=*

-DE6K602F(7LT63OM-@2SSIODSa#e using KLib le#el = compression )defaul"recommended #alue*

-DE6K6%2ST63OM-@2SSIODSa#e using KLib le#el ? compression )defaul" #alue is

=*-DE6K6DO63OM-@2SSIOD Sa#e wi"hou" KLib compression

1# (ppendi) FreeImage 3.15.1 documentation

8/13/2019 Free Image 3151

15/129


-DE6IDT2@L(320Sa#e using (dam in"erlacing )use R "o combine wi"ho"her sa#e flags*

-%M, -EM,--M

-DM602F(7LT Sa#es "he bi"map as a binary file

-DM6S(426@(W Sa#es "he bi"map as a binary file

-DM6S(426(S3II Sa#es "he bi"map as an (S3II file

TIFF TIFF602F(7LTSa#e using 33ITTF(; compression for $:bi" bi"mapsand LKW compression for any o"her bi"maps

TIFF63MBS"ores "ags for separa"ed 3MB )use R "o combine wi"hTIFF compression flags*

TIFF6-(3%ITS Sa#e using -(3%ITS compression!

TIFF602FL(T2Sa#e using 02FL(T2 compression )also known asKLI% compression*

TIFF6(0O%2602FL(T2 Sa#e using (0O%2 02FL(T2 compression

TIFF6DOD2 Sa#e wi"hou" any compression

TIFF633ITTF(> Sa#e using 33ITT Eroup > fax encoding

TIFF633ITTF(; Sa#e using 33ITT Eroup ; fax encodingTIFF6LKW Sa#e using LKW compression

TIFF6J-2ESa#e using J-2E compression )

8/13/2019 Free Image 3151

16/129


FreeImageIO io%ioGread_proc 5 N!LL% ++ usually not needed *or savingioG;rite_proc 5 7riteProc% ++ pointer to *unction t&at calls *;riteioGseeith a bitmap, or you >illhave a memory lea%!

1' (ppendi) FreeImage 3.15.1 documentation

8/13/2019 Free Image 3151

17/129

itmap information functions

Once a bi"map is loaded in"o memory, you can re"rie#e all kinds of informa"ion from i" oraccess specific par"s from "he bi"map, such as "he pixel bi"s and "he pale""e!

FreeImage-etImage$ype

DLL_API F/_I)A_"P DLL_CALLCONV FreeImage_etImage"ype(FIBI")AP 'di-$%

@e"urns "he da"a "ype of a bi"map )seeTable +*!

FreeImage-etColors9sed$ ; < $= +; >+

DLL_API unsigned DLL_CALLCONV FreeImage_etColors!sed(FIBI")AP 'di-$%

@e"urns "he number of colors used in a bi"map! This func"ion re"urns "he pale""e:sie forpalle"ised bi"maps, and for high:colour bi"maps!

There has been some cri"icism on "he name of "his func"ion! Some users expec" "hisfunc"ion "o re"urn "he ac"ual number of colors being used in a bi"map, while "he func"ion

ac"ually re"urns "he si@e of the palette! The name of "his func"ion origina"es from amember in %ITM(-IDFO.2(02@ named bi3lr7sed! The func"ion ac"ually re"urns "hecon"en" of "his member!

FreeImage-et44DLL_API unsigned DLL_CALLCONV FreeImage_etBPP(FIBI")AP 'di-$%

@e"urns "he sie of one pixel in "he bi"map in bi"s! For example when each pixel "akes >+:bi"sof space in "he bi"map, "his func"ion re"urns >+! -ossible bi" dep"hs are $, ;, + fors"andard bi"maps and $=:, >+:, ;

8/13/2019 Free Image 3151

18/129

FreeImage-etLine

DLL_API unsigned DLL_CALLCONV FreeImage_etLine(FIBI")AP 'di-$%

@e"urns "he wid"h of "he bi"map in by"es!

See also1 FreeImage6Ee"-i"ch!

There has been some cri"icism on "he name of "his func"ion! Some people expec" i" "o

re"urn a scanline in "he pixel da"a, while i" ac"ually re"urns "he >idth of the bitmap inbytes! (s far as I know "he "erm Line is common "erminology for "he wid"h of a bi"mapin by"es! I" is a" leas" used by Microsof" 0irec"!

FreeImage-et4itch

DLL_API unsigned DLL_CALLCONV FreeImage_etPitc&(FIBI")AP 'di-$%

@e"urns "he wid"h of "he bi"map in by"es, rounded "o "he nex" >+:bi" boundary, also known aspi"ch or s"ride or scan wid"h!

In FreeImage each scanline s"ar"s a" a 3'7bit boundary for performance reasons!

This accessor is essentialwhen using low le#el pixel manipula"ion func"ions )see also"he chap"er on -ixel access func"ions*!

FreeImage-etDI0i@e

DLL_API unsigned DLL_CALLCONV FreeImage_etDIB#ie(FIBI")AP 'di-$%

@e"urns "he sie of "he 0I%:elemen" of a FI%ITM(- in memory, i!e! "he%ITM(-IDFO.2(02@ 9 pale""e 9 da"a bi"s )no"e "ha" "his is no" "he realsie of a FI%ITM(-,only "he sie of i"s 0I%:elemen"*!

FreeImage-et4alette$ ; < $= +; >+

DLL_API /BM!AD 'DLL_CALLCONV FreeImage_etPalette(FIBI")AP 'di-$%

@e"urns a poin"er "o "he bi"map's pale""e! If "he bi"map doesn'" ha#e a pale""e )i!e! when "hepixel bi" dep"h is grea"er "han

8/13/2019 Free Image 3151

19/129

FreeImage-etDots4er!eter

DLL_API unsigned DLL_CALLCONV FreeImage_etDotsPer)eterR(FIBI")AP 'di-$%

@e"urns "he horion"al resolu"ion, in pixels:per:me"er, of "he "arge" de#ice for "he bi"map!

FreeImage-etDots4er!eter

DLL_API unsigned DLL_CALLCONV FreeImage_etDotsPer)eter(FIBI")AP 'di-$%

@e"urns "he #er"ical resolu"ion, in pixels:per:me"er, of "he "arge" de#ice for "he bi"map!

FreeImage-0etDots4er!eter

DLL_API void DLL_CALLCONV FreeImage_#etDotsPer)eterR(FIBI")AP 'di-0 unsigned res$%

Se" "he horion"al resolu"ion, in pixels:per:me"er, of "he "arge" de#ice for "he bi"map!

FreeImage-0etDots4er!eter

DLL_API void DLL_CALLCONV FreeImage_#etDotsPer)eter(FIBI")AP 'di-0 unsigned res$%

Se" "he #er"ical resolu"ion, in pixels:per:me"er, of "he "arge" de#ice for "he bi"map!

FreeImage-etInfo+

DLL_API BI")APINFO.AD/ 'DLL_CALLCONV FreeImage_etIn*o.eader(FIBI")AP 'di-$%

@e"urns a poin"er "o "he %ITM(-IDFO.2(02@ of "he 0I%:elemen" in a FI%ITM(-!

FreeImage-etInfo$ ; < $= +; >+

DLL_API BI")APINFO 'DLL_CALLCONV FreeImage_etIn*o(FIBI")AP 'di-$%

(lias for FreeImage6Ee"Info.eader "ha" re"urns a poin"er "o a %ITM(-IDFO ra"her "han "o a

%ITM(-IDFO.2(02@!

FreeImage-etColor$ype

DLL_API F/_I)A_COLO/_"P DLL_CALLCONV FreeImage_etColor"ype(FIBI")AP 'di-$%

In#es"iga"es "he color "ype of "he bi"map by reading "he bi"map's pixel bi"s and analysing"hem! FreeImage6Ee"3olorType can re"urn one of "he following #alues1


8/13/2019 Free Image 3151

20/129

alue Description

FI36MIDIS%L(3 Monochrome bi"map )$:bi"* 1 firs" pale""e en"ry is black! -alle"ised bi"map ); or + bi" bi"map, @E%($= or @E%(F*

FI363MB 3MB bi"map )>+ bi" only*

$able 5* F+-I!(-C/L/+-$4 constants.

To be &udged greyscale )i!e! FI36MIDIS%L(3*, a bi"map mus" ha#e a pale""e wi"h"hese charac"eris"ics1: The red, green, and blue #alues of each pale""e en"ry mus" be eCual,: The in"er#al be"ween ad&acen" pale""e en"ries mus" be posi"i#e and eCual "o $!

The 3MB color model )i!e! FI363MB* is "he preferred one, if one needs a pic"ure for"he prin" indus"ry or press! In almos" e#ery case, "his is done by graphic ar"is"s1 "hey"ake a @E% pic"ure )e!g! from a digi"al camera* and correc" "he #alues as appropria"efor "he pic"ure )single pixel, brigh"ness, con"ras"!!!*! Finally, "hey expor" an 3MBsepara"ed image! This will go direc"ly "o a layou" program and "hen "o "he prin"machines! Mos" FreeImage users will ne#er need "o use 3MB separa"ed images,because "he prin"er dri#ers will do "he con#ersion &ob! %u" in "he professional prin", "heproofed con#ersion is essen"ial "o ge" a brillian" prin" resul" )where no dri#er will dosome"hing like con#ersion*! Tha"'s why prin"ed pic"ures in some magaines look somuch be""er "han our home:made prin"s!

FreeImage-et+ed!as%$ ; < $= +; >+

DLL_API unsigned DLL_CALLCONV FreeImage_et/ed)as

8/13/2019 Free Image 3151

21/129

++ t&is code assumes t&ere is a -itmap loaded and++ present in a varia-le called Jdi-Kunsigned red_mas

8/13/2019 Free Image 3151

22/129

Sinclude 2FreeImageG&2

int main(int argc0 c&ar' argvQ$ 1

FIBI")AP '&DIB?@-pp 5 FreeImage_Load(FIF_B)P0 2testG-mp20 =$%i* (&DIB?@-pp$ 1 ++ colorTUuantie ?@-pp (results in a -pp -itmap to set transparency$ FIBI")AP '&DIB-pp 5 FreeImage_ColorMuantie(&DIB?@-pp0 FIM_7!M!AN"$%

++ get palette and *ind -rig&t green /BM!AD 'Palette 5 FreeImage_etPalette(&DIB-pp$% B" "ransparency?EQ% *or (unsigned i 5 =% i ?E% i$ 1 "ransparencyiQ 5 =FF% i* (PaletteiQGrg-reen W5 =F

PaletteiQGrg-Blue 55 === PaletteiQGrg-/ed 55 ===$ 1 "ransparencyiQ 5 ===% 9 9 ++ set t&e tranparency ta-le FreeImage_#et"ransparency"a-le(&DIB-pp0 "ransparency0 ?E$% ++ save -pp image as transparent PN FreeImage_#ave(FIF_PN0 &DIB-pp0 2testGpng20 =$%FreeImage_!nload(&DIB?@-pp$%

FreeImage_!nload(&DIB-pp$%

9return =%9

FreeImage-0et$ransparent$ ; < >+

DLL_API void DLL_CALLCONV FreeImage_#et"ransparent(FIBI")AP 'di-0 BOOL ena-led$%

Tells FreeImage if i" should make use of "he "ransparency "able or "he alpha channel "ha" mayaccompany a bi"map! When calling "his func"ion wi"h a bi"map whose bi"dep"h is differen" from$:, ;:, +:bi", "ransparency is disabled wha"e#er "he #alue of "he %oolean parame"er!

FreeImage-Is$ransparent

DLL_API BOOL DLL_CALLCONV FreeImage_Is"ransparent(FIBI")AP 'di-$%

@e"urns T@72 when "he "ransparency "able is enabled )$:, ;: or +:bi" images, @E%($= or @E%(F images*! @e"urns F(LS2o"herwise!

FreeImage-0et$ransparentInde)$ ; +:bi" 0I% ha#e e#ery ; by"es represen"ing a color associa"ed "o a alpha #alue )used"o indica"e "ransparency*, using "he same ordering as "he @E%X7(0 s"ruc"ure!

Don s"andard image "ypes such as shor", long, floa" or double do no" ha#e a color"able! -ixels are s"ored in a similar way as +bi"0I%, using "he same ordering as "he FI@E%U(V$= or FI@E%U(VF s"ruc"ures!

Color model

( color model is an abs"rac" ma"hema"ical model describing "he way colors can berepresen"ed as "uples of numbers, "ypically as "hree or four #alues or color componen"s )e!g!@E% and 3MB are color models*! FreeImage mainly uses "he @E%U(V color model "orepresen" pixels in memory!

.owe#er, "he pixel layou" used by "his model is OS dependan"! 7sing a by"e by by"e memory

order "o label "he pixel layou", "hen FreeImage uses a %E@U(V pixel layou" under a Li""le2ndian processor )Windows, Linux* and uses a @E%U(V pixel layou" under a %ig 2ndian

FreeImage 3.15.1 documentation (ppendi) '5

8/13/2019 Free Image 3151

30/129

processor )Mac OS or any %ig 2ndian Linux 8 7nix*! This choice was made "o ease "he useof FreeImage wi"h graphics (-I!

This sub"le difference is howe#er "ransparen" "o "he user! In order "o make pixel access OSindependen", FreeImage defines a se" of macros used "o se" or ge" indi#idual colorcomponen"s in a +;: or >+:bi" 0I%!

Channel 4i)el position (ssociated mas%

@ed FI6@E%(6@20 FI6@E%(6@206M(S

Ereen FI6@E%(6E@22D FI6@E%(6E@22D6M(S

%lue FI6@E%(6%L72 FI6@E%(6%L726M(S

(lpha FI6@E%(6(L-.( FI6@E%(6(L-.(6M(S

$able 6* 4i)el access macros and associated mas%s for '7 or 3'7bit images.

When accessing "o indi#idual color componen"s of a +;: or >+:bi" 0I%, you should

always use FreeImage macros or @E%T@I-L2 8 @E%X7(0 s"ruc"ures in order "owri"e OS independen" code!

The following sample shows how "o use "hese macros when working wi"h a >+:bi" dib1

++ Allocate a >?T-it di-FIBI")AP 'di- 5 FreeImage_Allocate(E?0 E?0 >?0 FI_/BA_/D_)A#60FI_/BA_/N_)A#60 FI_/BA_BL!_)A#6$%

++ Calculate t&e num-er o* -ytes per piel (> *or ?@T-it or @ *or >?T-it$int -ytespp 5 FreeImage_etLine(di-$ + FreeImage_et7idt&(di-$%

*or(unsigned y 5 =% y FreeImage_et.eig&t(di-$% y$ 1 B" '-its 5 FreeImage_et#canLine(di-0 y$%

*or(unsigned 5 =% FreeImage_et7idt&(di-$% $ 1 ++ #et piel color to green ;it& a transparency o* ? -itsFI_/BA_/DQ 5 =% -itsFI_/BA_/NQ 5 ?EE% -itsFI_/BA_BL!Q 5 =% -itsFI_/BA_ALP.AQ 5 ?%

++ [ump to net piel -its 5 -ytespp% 99

FreeImage-etitsDLL_API B" 'DLL_CALLCONV FreeImage_etBits(FIBI")AP 'di-$%

@e"urns a poin"er "o "he da"a:bi"s of "he bi"map! I" is up "o you "o in"erpre" "hese by"escorrec"ly, according "o "he resul"s of FreeImage6Ee"%--, FreeImage6Ee"@edMask,FreeImage6Ee"EreenMask and FreeImage6Ee"%lueMask!

For a performance reason, "he address re"urned by FreeImage6Ee"%i"s is aligned ona $= by"es alignmen" boundary!

Do"e1 FreeImage6Ee"%i"s will re"urn D7LL if "he bi"map does no" con"ain pixel da"a )i!e! if i"con"ains only header and possibly some or all me"ada"a*! See also FreeImage6.as-ixels!

'6 (ppendi) FreeImage 3.15.1 documentation

8/13/2019 Free Image 3151

31/129

++ t&is code assumes t&ere is a -itmap loaded and++ present in a varia-le called Ydi-Y

unsigned ;idt& 5 FreeImage_et7idt&(di-$%unsigned &eig&t 5 FreeImage_et.eig&t(di-$%unsigned pitc& 5 FreeImage_etPitc&(di-$%

F/_I)A_"P image_type 5 FreeImage_etImage"ype(di-$%

++ test piel access avoiding scanline calculations++ to speedTup t&e image processing

i*(image_type 55 FI"_/BF$ 1 B" '-its 5 (B"'$FreeImage_etBits(di-$% *or(y 5 =% y &eig&t% y$ 1 FI/BF 'piel 5 (FI/BF'$-its% *or( 5 =% ;idt&% $ 1 pielQGred 5 ?% pielQGgreen 5 ?% pielQG-lue 5 ?% 9 ++ net line -its 5 pitc&% 99else i*((image_type 55 FI"_BI")AP$ (FreeImage_etBPP(di-$ 55 ?@$$ 1 B" '-its 5 (B"'$FreeImage_etBits(di-$% *or(y 5 =% y &eig&t% y$ 1 B" 'piel 5 (B"'$-its% *or( 5 =% ;idt&% $ 1 pielFI_/BA_/DQ 5 ?% pielFI_/BA_/NQ 5 ?% pielFI_/BA_BL!Q 5 ?% piel 5 >% 9 ++ net line -its 5 pitc&% 99

FreeImage-et0canLine

DLL_API B" 'DLL_CALLCONV FreeImage_et#canLine(FIBI")AP 'di-0 int scanline$%

@e"urns a poin"er "o "he s"ar" of "he gi#en scanline in "he bi"map's da"a:bi"s!

I" is up "o you "o in"erpre" "hese by"es correc"ly, according "o "he resul"s ofFreeImage6Ee"%-- andFreeImage6Ee"ImageType )see "he following sample*!

When working wi"h FIT6IDT>+ or FIT67IDT>+ image "ypes, you should cas" "he resul"of FreeImage6Ee"ScanLine wi"h respec"i#ely a LODE or a 0WO@0 da"a "ype! This is

because "he sie of a long is >+:bi" under Windows and is =;:bi" under 7nix or Linux!7sing LODE or 0WO@0 da"a "ype ensure "ha" you are working wi"h >+:bi" "ypes,wha"e#er "he pla"form!

Do"e1 FreeImage6Ee"ScanLine will re"urn D7LL if "he bi"map does no" con"ain pixel da"a )i!e!if i" con"ains only header and possibly some or all me"ada"a*! See also FreeImage6.as-ixels!

FreeImage 3.15.1 documentation (ppendi) '"

8/13/2019 Free Image 3151

32/129

++ t&is code assumes t&ere is a -itmap loaded and++ present in a varia-le called JimageK

unsigned 0 y%

F/_I)A_"P image_type 5 FreeImage_etImage"ype(image$%

++ test piel access

s;itc&(image_type$ 1 case FI"_BI")APX i*(FreeImage_etBPP(image$ 55 $ 1 *or(y 5 =% y FreeImage_et.eig&t(image$% y$ 1 B" '-its 5 (B" '$FreeImage_et#canLine(image0 y$% *or( 5 =% FreeImage_et7idt&(image$% $ 1 -itsQ 5 ?% 9 9 9 -rea

8/13/2019 Free Image 3151

33/129

-itsQGgreen 5 ?% -itsQG-lue 5 ?% 9 9 -rea+

DLL_API BOOL DLL_CALLCONV FreeImage_etPielColor(FIBI")AP 'di-0 unsigned 0 unsignedy0 /BM!AD 'value$%

Ee" "he pixel color of a $=:, +;: or >+:bi" image a" posi"ion )x, y*, including range check )slowaccess*! -arame"er x is "he pixel posi"ion in horion"al direc"ion, and parame"er y is "he pixelposi"ion in #er"ical direc"ion! The func"ion re"urns T@72 on success, and re"urns F(LS2o"herwise )e!g! for pale""ied images*!

FreeImage-0et4i)elInde)$ ; +

DLL_API BOOL DLL_CALLCONV FreeImage_#etPielColor(FIBI")AP 'di-0 unsigned 0 unsignedy0 /BM!AD 'value$%

Se" "he pixel color of a $=:, +;: or >+:bi" image a" posi"ion )x, y*, including range check )slowaccess*! -arame"er x is "he pixel posi"ion in horion"al direc"ion, and parame"er y is "he pixelposi"ion in #er"ical direc"ion! The func"ion re"urns T@72 on success, and re"urns F(LS2o"herwise )e!g! for pale""ied images*!

3# (ppendi) FreeImage 3.15.1 documentation

8/13/2019 Free Image 3151

35/129

Conversion functions

The following func"ions make i" possible "o con#er" a bi"map from one bi" dep"h "o ano"her!

7nder a Li""le 2ndian OS )Windows, Linux on -3*, bi"maps are always s"ored inmemory as blue firs", "hen green "hen red, "hen alpha )%E@U(V con#en"ion*! 7nder a%ig 2ndian OS, FreeImage uses "he @E%U(V con#en"ion! .owe#er, "hese por"abili"yconsidera"ions are "ransparen"ly handled by "he con#ersion func"ions, so "ha" you canla"er sa#e con#er"ed bi"maps in an OS independen" manner!

FreeImage-Convert$oits$ ; < $= +; >+

DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"o@Bits(FIBI")AP 'di-$%

3on#er"s a bi"map "o ; bi"s! If "he bi"map was a high:color bi"map )$=, +; or >+:bi"* or if i" wasa monochrome or greyscale bi"map )$ or

8/13/2019 Free Image 3151

36/129

FreeImage-Convert$o16its555$ ; < $= +; >+

DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"oBitsEEE(FIBI")AP 'di-$%

3on#er"s a bi"map "o $= bi"s, where each pixel has a color pa""ern of P bi"s red, P bi"s greenand P bi"s blue! One bi" in each pixel is unused! ( clone of "he inpu" bi"map is re"urned for $=:bi" PPP bi"maps

FreeImage-Convert$o16its565$ ; < $= +; >+

DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"oBitsEE(FIBI")AP 'di-$%

3on#er"s a bi"map "o $= bi"s, where each pixel has a color pa""ern of P bi"s red, = bi"s greenand P bi"s blue! ( clone of "he inpu" bi"map is re"urned for $=:bi" P=P bi"maps

FreeImage-Convert$o'its$ ; < $= +; >+ ;

8/13/2019 Free Image 3151

37/129

Wu, iaolin, 2fficien" S"a"is"ical 3ompu"a"ions for Op"imal 3olor Xuan"ia"ion! In EraphicsEems, #ol! II, p! $+=:$>>! UOnlineV h""p188www!ece!mcmas"er!ca8Zxwu8

0ekker (! .!, ohonen neural ne"works for op"imal color Cuan"ia"ion! De"work1 3ompu"a"ionin Deural Sys"ems, 4olume P, Dumber >, Ins"i"u"e of -hysics -ublishing, $??;! UOnlineVh""p188members!oemail!com!au8Zdekker8D27X7(DT!.TML

FreeImage-Color8uanti@e)+;

DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_ColorMuantie(FIBI")AP 'di-0F/_I)A_M!AN"I] Uuantie FI_DFA!L"(FIM_7!M!AN"$0 int Palette#ie FI_DFA!L"(?E$0int /eserve#ie FI_DFA!L"(=$0 /BM!AD '/eservePalette FI_DFA!L"(N!LL$$%

FreeImage63olorXuan"ie2x is an ex"ension "o "he FreeImage63olorXuan"iefunc"ion "ha"pro#ides addi"ional op"ions used "o Cuan"ie a +;:bi" image "o any number of colors )up "o+P=*, as well as Cuan"ie a +;:bi" image using a par"ial or full pro#ided pale""e!

The #alette$i"eparame"er is "he sie of "he desired ou"pu" pale""e! %eser&e$i"eis "he sie of"he pro#ided pale""e, gi#en by "he %eser&e#aletteinpu" array!

++ t&is code assumes t&ere is a ?@T-it -itmap loaded and++ present in a varia-le called Ydi-Y

/BM!AD ;e-_palette?Q%++ list o* t&e ? 2;e-Tsa*e2 colors (/B increments o* E$++ GGG

++ Per*orm a color Uuantiation using a user supplied palette++ "&e goal o* FreeImage_ColorMuantie ;ill -e to *ill in++ t&e remaining >^ palette entries ;it& t&e -est c&oices -ased++ on t&e input image0 t&en use t&e palette o* sie ?EE to Uuantie t&e imageG

++ "&e output palette ;ill contain a mi o* t&e ? and >^ colors0++ -ut not in any particular orderG Palette entry ?EE (t&e ?Et& entry$++ is unused in t&e image0 and ;ill -e -lac< in t&e paletteG++ "&is allo;s t&e user to use t&e palette entry S ?EE *or transparency

++ ;it&out ;orrying a-out ma

8/13/2019 Free Image 3151

38/129

FreeImage-$hreshold$ ; < $= +; >+

DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_"&res&old(FIBI")AP 'di-0 B" "$%

3on#er"s a bi"map "o $:bi" monochrome bi"map using a "hreshold T be"ween U!!+PPV! Thefunc"ion firs" con#er"s "he bi"map "o a +

DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Dit&er(FIBI")AP 'di-0 F/_I)A_DI"./algorit&m$%

3on#er"s a bi"map "o $:bi" monochrome bi"map using a di"hering algori"hm! For $:bi" inpu"bi"maps, "he func"ion clones "he inpu" bi"map and builds a monochrome pale""e!

The algorit'm parame"er specifies "he di"hering algori"hm "o be used! The func"ion firs"con#er"s "he bi"map "o a : =x= ma"rix*

FI063L7ST2@

8/13/2019 Free Image 3151

39/129

When "he source bi"map uses a >+:bi" padding, you can calcula"e "he pi"ch using "hefollowing formula1in" pi"ch ))))bpp A wid"h* 9 >$* 8 >+* A ;*

FreeImage-Convert$o+a>its$ ; < $= +; >+

DLL_API void DLL_CALLCONV FreeImage_Convert"o/a;Bits(B" '-its0 FIBI")AP 'di-0 intpitc&0 unsigned -pp0 unsigned red_mas?T-it ra; -u**er (topTle*t piel *irst$++ TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTFIBI")AP 'src 5 FreeImage_Convert"o>?Bits(di-$%FreeImage_!nload(di-$%

++ Allocate a ra; -u**erint ;idt& 5 FreeImage_et7idt&(src$%int &eig&t 5 FreeImage_et.eig&t(src$%int scan_;idt& 5 FreeImage_etPitc&(src$%B" '-its 5 (B"'$malloc(&eig&t ' scan_;idt&$%

++ convert t&e -itmap to ra; -its (topTle*t piel *irst$FreeImage_Convert"o/a;Bits(-its0 src0 scan_;idt&0 >?0 FI_/BA_/D_)A#60 FI_/BA_/N_)A#60 FI_/BA_BL!_)A#60

"/!$%FreeImage_!nload(src$%

++ convert a >?T-it ra; -u**er (topTle*t piel *irst$ to a FIBI")AP++ TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTFIBI")AP 'dst 5 FreeImage_ConvertFrom/a;Bits(-its0 ;idt&0 &eig&t0 scan_;idt&0 >?0 FI_/BA_/D_)A#60 FI_/BA_/N_)A#60 FI_/BA_BL!_)A#60 FAL#$%

FreeImage-Convert$o0tandard$ype$ ; < $= +; >+ $=7IDT$= >+FLO(T =;0O7%L2 $=IDT$= >+7IDT>+8IDT>+ +x=;3OM-L2

DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"o#tandard"ype(FIBI")AP 'src0 BOOLscale_linear FI_DFA!L"("/!$$%

3on#er"s a non s"andard image whose color "ype is FI36MIDIS%L(3 "o a s"andard

8/13/2019 Free Image 3151

40/129

FreeImage-Convert$o$ype

DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"o"ype(FIBI")AP 'src0 F/_I)A_"Pdst_type0 BOOL scale_linear FI_DFA!L"("/!$$%

3on#er"s an image of any "ype "o "ype dst_type! When dst_typeis eCual "o FIT6%ITM(-, "he

func"ion calls FreeImage63on#er"ToS"andardType! O"herwise, con#ersion is done usings"andard 3 language cas"ing con#en"ion! When a con#ersion is no" allowed, a D7LL #alue isre"urned and an error message is "hrown )i" can be ca"ched usingFreeImage6Se"Ou"pu"Message*! The following con#ersions are curren"ly allowed by "helibrary )o"her con#ersions may be added easily if needed*1

FIT6

%ITM(-

FIT6

7IDT$=

FIT6

IDT$=

FIT6

7IDT>+

FIT6

IDT>+

FIT6

FLO(T

FIT6

0O7%L2

FIT6

3OM-L2

FIT6

@E%$=

FIT6

@E%($=

FIT6

@E%F

FIT6

@E%(F

color legend

FIT6%ITM(- re"urns FreeImage63lone

FIT67IDT$= re"urns FreeImage63on#er"To+;%i"s

FIT6IDT$= re"urns FreeImage63on#er"To>+%i"s

FIT67IDT>+ re"urns FreeImage63on#er"To7IDT$=

FIT6IDT>+ re"urns FreeImage63on#er"To@E%$=

FIT6FLO(T re"urns FreeImage63on#er"ToFloa"

FIT60O7%L2 re"urns FreeImage63on#er"To@E%F

FIT63OM-L2 re"urns FreeImage63on#er"ToS"andardType

FIT6@E%$= con#ersion is done using

FIT6@E%($= s"andard 3 language cas"ing con#en"ion

FIT6@E%F

FIT6@E%(F

$able =* itmap type conversions allo>ed by FreeImage.

FreeImage-Convert$oFloat$ ; < $= +; >+ $=7IDT$= ;+FLO(T ?=@E%F $+P so "ha" "heou"pu" image is in "he range U!!$V!

FIT6@E%U(V$= "ype1 "he inpu" dib is firs" con#er"ed "o a $=:bi" greyscale image, "heneach pixel #alue is di#ided by =PP>P so "ha" "he ou"pu" image is in "he range U!!$V!When an alpha channel is presen" in "he source, i" is simply ignored by "hecon#ersion func"ion!

FIT6@E%U(VF "ype1 "he inpu" dib is con#er"ed "o a >+:bi" floa" image! When an alphachannel is presen" in "he source, i" is simply ignored by "he con#ersion func"ion!

For >+:bi" floa" inpu" images, a clone of "he inpu" is re"urned!

36 (ppendi) FreeImage 3.15.1 documentation

8/13/2019 Free Image 3151

41/129

When crea"ing "he greyscale floa" image, "he luminance L )or greyscale in"ensi"y* of aresul" pixel is calcula"ed from "he s@E% model using a 0=P whi"e poin", using "he@ec!? formula 1

L ) !+$+= A r * 9 ) !$P+ A g * 9 ) !++ A b *The #alues !+$+=, !$P+ and !++ represen" "he rela"i#e red, green, and blue

in"ensi"ies!

FreeImage-Convert$o+F$ ; < $= +; >+ $=7IDT$= ;+FLO(T ?=@E%F $++:bi" @E%)(* s"andard image or a ;+ $=7IDT$= ;

8/13/2019 Free Image 3151

42/129

$one mapping operators

Tone mapping opera"ors are used "o compress a large range of pixel luminances in"o asmaller range "ha" is sui"able for display on de#ices wi"h limi"ed dynamic range )e!g! displayde#ices such as 3@Ts or L30s and prin" media*!

In principle "his problem is simple1 we need "o "urn an image wi"h a large range of numbersin"o an image con"aining in"egers in "he range of "o +PP such "ha" we can display i" on aprin"er or a moni"or! This sugges"s linear scaling as a possible solu"ion! .owe#er, "hisapproach is flawed because de"ails in "he ligh" or dark areas of "he image will be los" due "osubseCuen" Cuan"ia"ion, and "he displayed image will "herefore no" be percei#ed "he same as"he scene "ha" was pho"ographed! For "his reason, more elabora"e algori"hms, called "onemapping opera"ors, ha#e been proposed "o accura"ely render .igh 0ynamic @ange images!

FreeImage-$one!apping;*

FITMO6@2ID.(@0P 0ynamic range reduc"ion inspired by pho"orecep"or physiology )2! @einhard,+P*

FITMO6F(TT(L+ Eradien" domain .igh 0ynamic @ange compression )@! Fa""al, ++*

$able 1#* F+-I!(-$!/ constants.

The meaning of "he first_param and second_param parame"ers depends on "he choosenalgori"hm )see "he defini"ion of each "one mapping opera"or below*! When bo"h parame"ersare se" "o ero, a defaul" se" of parame"ers is used!

++ load a .D/ /B Float imageFIBI")AP 'src 5 FreeImage_Load(FIF_.D/0 memorialG&drH0 =$%++ create a ?@T-it tone mapped image suita-le *or display

FIBI")AP 'dst 5 FreeImage_"one)apping(src0 FI")O_D/AO=>$%++ :FreeImage_!nload(src$%FreeImage_!nload(dst$%

FreeImage-$moDrago#3;

8/13/2019 Free Image 3151

43/129

7pon en"ry, gamma)where gamma * is a gamma correc"ion "ha" is applied after"he "onemapping! ( #alue of $ means no correc"ion! The defaul" +!+ #alue, used in "he originalau"hor's paper, is recommended as a good s"ar"ing #alue!

The exposureparame"er, in "he range U:, 4ol!++, Do, >, pp! ;$?:;+=, +>!

FreeImage-$mo+einhard#5;, $!U, con"rols "he o#erall image con"ras"! Whenusing "he defaul" #alue )*, "his parame"er is calcula"ed au"oma"ically!

+eference

2! @einhard and ! 0e#lin, 0ynamic @ange @educ"ion Inspired by -ho"orecep"or -hysiology!I222 Transac"ions on 4isualia"ion and 3ompu"er Eraphics, $$)$*, Jan8Feb +P!

2! @einhard, -arame"er es"ima"ion for pho"ographic "one reproduc"ion, Journal of EraphicsTools, #ol! , no! $, pp! ;PYP$, +>!

FreeImage-$mo+einhard#5);, $!U, con"rols "he o#erall image con"ras"! Whenusing "he defaul" #alue )*, "his parame"er is calcula"ed au"oma"ically!

The adaptationparame"er, in range U1$V, con"rols "he le#el of ligh" adap"a"ion! When using"he defaul" #alue )$*, adap"a"ion is local and is based on "he pixel in"ensi"y! When using a#alue , "he adap"a"ion is global and is based on "he a#erage channel in"ensi"y!

The color_correction parame"er, in range U1$V, con"rols "he le#el of chroma"ic adap"a"ion!7sing "he defaul" #alue )* means no chroma"ic adap"a"ion, i!e! "he adaptation le#el is "he

same for all > color channels! Se""ing "his #alue "o $ means "ha" each @, E, % channel is"rea"ed independen"ly!

FreeImage 3.15.1 documentation (ppendi) 3=

8/13/2019 Free Image 3151

44/129

+eference

2! @einhard and ! 0e#lin, 0ynamic @ange @educ"ion Inspired by -ho"orecep"or -hysiology!I222 Transac"ions on 4isualia"ion and 3ompu"er Eraphics, $$)$*, Jan8Feb +P!

2! @einhard, -arame"er es"ima"ion for pho"ographic "one reproduc"ion, Journal of EraphicsTools, #ol! , no! $, pp! ;PYP$, +>!

FreeImage-$moFattal#';*1+;?Y+P=, ++!

# (ppendi) FreeImage 3.15.1 documentation

8/13/2019 Free Image 3151

45/129

ICC profile functions

Whene#er an I33 profile is a#ailable in a bi"map file i" is "ransparen"ly loaded and s"ored in"he FI%ITM(-! On "he o"her side, whene#er an I33 profile is s"ored in a FI%ITM(-, i" is"ransparen"ly s"ored in "he bi"map file when sa#ing, pro#ided "he ou"pu"F@22IM(E26FO@M(T suppor"s I33 profiles )a plugin can be asked for I33 profile suppor"using FreeImage6FIFSuppor"sI33-rofiles* !

FreeImage defines a s"ruc"ure called FII33-@OFIL2, "ha" is used "o access "his I33 profile!The s"ruc"ure can "hen be used wi"h any color managemen" engine "o perform bi"map"ransforma"ions be"ween "wo I33 profiles!

If "he FII33-@OFIL2 is flagged wi"h FII3363OLO@6IS63MB "he bi"map is arepresen"a"ion of a 3MB separa"ion! Toge"her wi"h color managemen" "hisinforma"ion is impor"an", because "he profile da"a and "he bi"map mus" reside in "hesame color model )e!g! @E% or 3MB*!

In almos" all cases, "he bi"map is loaded as an @E% represen"a"ion! I" may depend on specialflags "o FreeImage6Load, whe"her "he original color represen"a"ion is preser#ed or no"!

++ load a -itmap *rom *ile0 en*orce to preserve t&e++ C)6 separated data *rom "IFF (no /B conversion done$

FIBI")AP '-itmap 5 FreeImage_Load (FIF_"IFF0 name0 "IFF_C)6$%

i* (-itmap$ 1

++ test *or /B or C)6 colour space

i* ((FreeImage_etICCPro*ile(-itmap$TW*lags FIICC_COLO/_I#_C)6$ 55 FIICC_COLO/_I#_C)6$

++ ;e are in C)6 colour space

else ++ ;e are in /B colour space

9

I33 profiles are curren"ly suppor"ed by TIFF, -DE and J-2E plugins!

FreeImage-etICC4rofile

DLL_API FIICCP/OFIL 'DLL_CALLCONV FreeImage_etICCPro*ile(FIBI")AP 'di-$%

@e"rie#es a poin"er "o "he FII33-@OFIL2 da"a of "he bi"map! This func"ion can also be calledsafely, when "he original forma" does no" suppor" profiles!


8/13/2019 Free Image 3151

46/129


++ retrieve a pointer to FIICCP/OFIL structure

FIICCP/OFIL 'pro*ile 5 FreeImage_etICCPro*ile(-itmap$%

I* (pro*ileTWdata$ 1

++ pro*ile data present

9

FreeImage-CreateICC4rofile

DLL_API FIICCP/OFIL 'DLL_CALLCONV FreeImage_CreateICCPro*ile(FIBI")AP 'di-0 void'data0 long sie$%

3rea"es a new FII33-@OFIL2 block from I33 profile da"a pre#iously read from a file or buil"by a color managemen" sys"em! The profile da"a is a""ached "o "he bi"map! The func"ionre"urns a poin"er "o "he FII33-@OFIL2 s"ruc"ure crea"ed!


D7O/D sie 5 _*ilelengt&(*ileno(&Pro*ile$$%

++ read pro*ile data *rom *ile and eroTterminate

i* (sie (data 5 (void '$malloc(sie $$$ 1 sie 5 *read(data0 0 sie0 &Pro*ile$% '(data sie$ 5 =%

++ attac& retrieved pro*ile data to -itmap

FIICCP/OFIL 'pro*ile 5 FreeImage_CreateICCPro*ile (-itmap0 data0 sie$%

*ree (data$%9

FreeImage-DestroyICC4rofile

DLL_API void DLL_CALLCONV FreeImage_DestroyICCPro*ile(FIBI")AP 'di-$%

This func"ion des"roys an FII33-@OFIL2 pre#iously crea"ed by FreeImage63rea"eI33-rofile!(f"er "his call "he bi"map will con"ain no profile informa"ion! This func"ion should be called "oensure "ha" a s"ored bi"map will no" con"ain any profile informa"ion!

++ t&is code assumes t&ere is a -itmap loaded and

++ present in a varia-le called J-itmapK

++ destroy pro*ile possi-ly present

FreeImage_DestroyICCPro*ile(-itmap$%

++ store pro*ileTless -itmap

FreeImage_#ave (FIF_"IFF0 -itmap0 name0 *lags$%

' (ppendi) FreeImage 3.15.1 documentation

8/13/2019 Free Image 3151

47/129

4lugin functions

Through a#erage use you won'" probably no"ice i", FreeImage is plugin dri#en! 2ach bi"maploader8sa#er is in fac" a plugin module "ha" is linked inside "he in"egra"ed plugin manager! Bouwon'" no"ice i", un"il you decide "o wri"e your own plugins!

(lmos" e#ery plugin in FreeImage is incorpora"ed direc"ly in"o "he 0LL! The reason why "his isdone "his way is a mix"ure of e#olu"ion and design! The firs" #ersions of FreeImage )ac"ually,abou" "he whole firs" year of i"s exis"ence* i" had no no"ion of plugins! This mean" "ha" allbi"map func"ionali"y was a#ailable only from "he main 0LL! In "he second year Floris decided"o crea"e plugins, because he wan"ed "o suppor" some bi"maps forma"s "ha" ha#e licenseres"ric"ions on "hem, such as EIF! In fear "ha" he would pu" all i"s bi"map loaders8sa#ers in "iny0LLs "ha" would spla""er "he hard dri#e, his mos" impor"an" \cus"omer' s"rongly encouragedhim "o keep as much bi"map forma"s in one 0LL as possible! .e "ook his word for i" and i"lead "o "he design you see here "oday!

The ac"ual plugin sys"em e#ol#ed from some"hing #ery simple "o a #ery flexible mechanism"ha" he now of"en reuses in o"her sof"ware! (" "his momen" i"'s possible "o ha#e plugins in "hemain F@22IM(E2!0LL, in ex"ernal 0LLs, and e#en direc"ly in an applica"ion "ha" dri#esFreeImage!

FreeImage-etFIFCount

DLL_API int DLL_CALLCONV FreeImage_etFIFCount($%

@e"rie#es "he number of F@226IM(E26FO@M(T iden"ifiers being curren"ly regis"ered! InFreeImage F@226IM(E26FO@M(T became, "hrough e#olu"ion, synonymous wi"h plugin!

FreeImage-0et4luginnabled

DLL_API int DLL_CALLCONV FreeImage_#etPluginna-led(F/_I)A_FO/)A" *i*0 BOOLena-le$%

2nables or disables a plugin! ( disabled plugin canno" be used "o impor" and expor" bi"maps,nor will i" iden"ify bi"maps! When called, "his func"ion re"urns "he pre#ious plugin s"a"e )T@72 8$ or F(LS2 8 *, or Y$ if "he plugin doesn'" exis"!

FreeImage-Is4luginnabled

DLL_API int DLL_CALLCONV FreeImage_IsPluginna-led(F/_I)A_FO/)A" *i*$%

@e"urns T@72 when "he plugin is enabled, F(LS2 when "he plugin is disabled, :$ o"herwise!

FreeImage-etFIFFromFormat

DLL_API F/_I)A_FO/)A" DLL_CALLCONV FreeImage_etFIFFromFormat(const c&ar '*ormat$%

@e"urns a F@226IM(E26FO@M(T iden"ifier from "he forma" s"ring "ha" was used "o regis"er"he FIF!


8/13/2019 Free Image 3151

48/129

FreeImage-etFIFFrom!ime

DLL_API F/_I)A_FO/)A" DLL_CALLCONV FreeImage_etFIFFrom)ime(const c&ar 'mime$%

@e"urns a F@226IM(E26FO@M(T iden"ifier from a MIM2 con"en" "ype s"ring )MIM2 s"andsfor Mul"ipurpose In"erne" Mail 2x"ension*!

F/_I)A_FO/)A" *i* 5 FreeImage_etFIFFrom)ime(image+pngH$%I*(*i* 45 FIF_!N6NO7N$ 1assert(*i* 55 FIF_PN$%

9

FreeImage-etFIF!ime$ype

DLL_API const c&ar 'DLL_CALLCONV FreeImage_etFIF)ime"ype(F/_I)A_FO/)A" *i*$%

Ei#en a F@226IM(E26FO@M(T iden"ifier, re"urns a MIM2 con"en" "ype s"ring )MIM2 s"andsfor Mul"ipurpose In"erne" Mail 2x"ension*!

FreeImage-etFormatFromFIF

DLL_API const c&ar 'DLL_CALLCONV FreeImage_etFormatFromFIF(F/_I)A_FO/)A" *i*$%

@e"urns "he s"ring "ha" was used "o regis"er a plugin from "he sys"em assignedF@226IM(E26FO@M(T!

FreeImage-etFIF)tensionList

DLL_API const c&ar 'DLL_CALLCONV FreeImage_etFIFtensionList(F/_I)A_FO/)A" *i*$%

@e"urns a comma:delimi"ed file ex"ension lis" describing "he bi"map forma"s "he gi#en plugincan read and8or wri"e!

(ppendi) FreeImage 3.15.1 documentation

8/13/2019 Free Image 3151

49/129

+''Builds a series o* string pairs t&at speci*y *ilters you can apply to load a *ileG"&e *ilter string is to -e used -y a YFile OpenY dialog -o(etOpenFileName or CFileDialog$G,param sFilter Input and output parameterG sFilter is an array o* c&ar ;&ose lengt&s&ould -e ?=@ or moreG,return /eturns t&e num-er o* supported import *ormats'+

int etOpenFilter#tring(c&ar 'sFilter$ 1 int i0 iCount% c&ar Filter?=@Q% c&ar 'to

8/13/2019 Free Image 3151

50/129

@e"urns a regular expression s"ring "ha" can be used by a regular expression engine "oiden"ify "he bi"map! FreeImageX" makes use of "his func"ion!

FreeImage-etFIFFromFilename

DLL_API F/_I)A_FO/)A" DLL_CALLCONV FreeImage_etFIFFromFilename(const c&ar'*ilename$%

This func"ion "akes a filename or a file:ex"ension and re"urns "he plugin "ha" can read8wri"efiles wi"h "ha" ex"ension in "he form of a F@226IM(E26FO@M(T iden"ifier!

+'' eneric image loader,param lpsPat&Name Pointer to t&e *ull *ile name,param *lag Optional load *lag constant,return /eturns t&e loaded di- i* success*ul0 returns N!LL ot&er;ise'+FIBI")AP' enericLoader(const c&ar' lpsPat&Name0 int *lag$ 1 F/_I)A_FO/)A" *i* 5 FIF_!N6NO7N% ++ c&ec< t&e *ile signature and deduce its *ormat ++ (t&e second argument is currently not used -y FreeImage$

*i* 5 FreeImage_etFile"ype(lpsPat&Name0 =$% i*(*i* 55 FIF_!N6NO7N$ 1 ++ no signature \ ++ try to guess t&e *ile *ormat *rom t&e *ile etension *i* 5 FreeImage_etFIFFromFilename(lpsPat&Name$% 9 ++ c&ec< t&at t&e plugin &as reading capa-ilities GGG i*((*i* 45 FIF_!N6NO7N$ FreeImage_FIF#upports/eading(*i*$$ 1 ++ o

8/13/2019 Free Image 3151

51/129

+'' eneric image ;riter,param di- Pointer to t&e di- to -e saved,param lpsPat&Name Pointer to t&e *ull *ile name,param *lag Optional save *lag constant,return /eturns true i* success*ul0 returns *alse ot&er;ise'+-ool eneric7riter(FIBI")AP' di-0 const c&ar' lpsPat&Name0 int *lag$ 1 F/_I)A_FO/)A" *i* 5 FIF_!N6NO7N%

BOOL -#uccess 5 FAL#% ++ "ry to guess t&e *ile *ormat *rom t&e *ile etension *i* 5 FreeImage_etFIFFromFilename(lpsPat&Name$% i*(*i* 45 FIF_!N6NO7N $ 1 ++ C&ec< t&at t&e di- can -e saved in t&is *ormat BOOL -Can#ave%

F/_I)A_"P image_type 5 FreeImage_etImage"ype(di-$% i*(image_type 55 FI"_BI")AP$ 1 ++ standard -itmap type ++ c&ec< t&at t&e plugin &as su**icient ;riting ++ and eport capa-ilities GGG 7O/D -pp 5 FreeImage_etBPP(di-$% -Can#ave 5 (FreeImage_FIF#upports7riting(*i*$

FreeImage_FIF#upportsportBPP(*i*0 -pp$$% 9 else 1 ++ special -itmap type

++ c&ec< t&at t&e plugin &as su**icient eport capa-ilities -Can#ave 5 FreeImage_FIF#upportsport"ype(*i*0 image_type$% 9

i*(-Can#ave$ 1 -#uccess 5 FreeImage_#ave(*i*0 di-0 lpsPat&Name0 *lag$% 9 9 return (-#uccess 55 "/!$ \ true X *alse%9

FreeImage-FIF0upports)port$ype

DLL_API BOOL DLL_CALLCONV FreeImage_FIF#upportsport"ype(F/_I)A_FO/)A" *i*0F/_I)A_"P type$%

@e"urns T@72 if "he plugin belonging "o "he gi#en F@226IM(E26FO@M(T can sa#e abi"map in "he desired da"a "ype, re"urns F(LS2 o"herwise! See "he lis" of Suppor"ed fileforma"s in "he appendix for a lis" of plugins "ha" can sa#e non:s"andard images!

FreeImage-FIF0upports)port44$ ; < $= +; >+

DLL_API BOOL DLL_CALLCONV FreeImage_FIF#upportsportBPP(F/_I)A_FO/)A" *i*0 int-pp$%

@e"urns T@72 if "he plugin belonging "o "he gi#en F@226IM(E26FO@M(T can sa#e abi"map in "he desired bi" dep"h, re"urns F(LS2 o"herwise!

FreeImage 3.15.1 documentation (ppendi) "

8/13/2019 Free Image 3151

52/129

+''Builds a series o* string pairs t&at speci*y *ilters you can apply to save a *ileG"&e *ilter string is to -e used -y a YFile #ave AsY dialog -o (et#aveFileName orCFileDialog$G,param sFilter Input and output parametersG sFilter is an array o* c&ar ;&oselengt& s&ould -e ?=@ or moreG,param -pp "&e -it dept& o* t&e image to -e savedG,param image_type "&e image type to -e saved

,return /eturn t&e num-er o* supported eport *ormats'+int et#aveAsFilter#tring(c&ar 'sFilter0 7O/D -pp0 F/_I)A_"P image_type$ 1 int i0 iCount% c&ar Filter?=@Q% c&ar 'to$ 4strncmp(Filter0 2PP)20 >$$$ continue% i*((-pp 55 $ (4strncmp(Filter0 2PB)20 >$ 4strncmp(Filter0 2PP)20 >$$$ continue% i*((-pp 55 ?@$ (4strncmp(Filter0 2P)20 >$ 4strncmp(Filter0 2PB)20 >$$$ continue%

++ Description sprint*(Filter0 28s (8s$20 FreeImage_etFIFDescription((F/_I)A_FO/)A"$i$0

FreeImage_etFIFtensionList((F/_I)A_FO/)A"$i$$% strcat(sFilter0 Filter$% ++ tension(s$ strcpy(Filter0 FreeImage_etFIFtensionList((F/_I)A_FO/)A"$i$$% to

8/13/2019 Free Image 3151

53/129

++ determine0 ;&et&er pro*ile support is present

i* (FreeImage_FIF#upportsICCPro*iles(FIF_"IFF$$ 1

++ pro*ile support present

9

FreeImage-FIF0upports:o4i)els

DLL_API BOOL DLL_CALLCONV FreeImage_FIF#upportsNoPiels(F/_I)A_FO/)A" *i*$%

@e"urns T@72 if "he plugin belonging "o "he gi#en F@226IM(E26FO@M(T can load a fileusing "he FIF6LO(06DO-I2LS load flag! If T@72, a loader can load header only da"a andpossibly some me"ada"a

++ determine0 ;&et&er J&eader onlyK support is present

i* (FreeImage_FIF#upportsNoPiels(FIF_ZP$$ 1

++ J&eader onlyK support present

9

FreeImage-+egisterLocal4lugin

DLL_API F/_I)A_FO/)A" DLL_CALLCONV FreeImage_/egisterLocalPlugin(FI_InitProcproc_address0 const c&ar '*ormat FI_DFA!L"(=$0 const c&ar 'description FI_DFA!L"(=$0const c&ar 'etension FI_DFA!L"(=$0 const c&ar 'regepr FI_DFA!L"(=$$%

@egis"ers a new plugin "o be used in FreeImage! The plugin is residing direc"ly in "heapplica"ion dri#ing FreeImage! The firs" parame"er is a poin"er "o a func"ion "ha" is used "oini"ialise "he plugin! The ini"ialia"ion func"ion is responsible for filling in a -lugin s"ruc"ure and

s"oring a sys"em:assigned forma" iden"ifica"ion number used for message logging!

FreeImage 3.15.1 documentation (ppendi) =

8/13/2019 Free Image 3151

54/129

static int s_*ormat_id%

void stdcallInit(Plugin 'plugin0 int *ormat_id$ 1 s_*ormat_id 5 *ormat_id%

++ pointer to a *unction t&at returns a typeTstring ++ *or t&e -itmapG For eample0 a plugin t&at loads

++ B)Ps returns t&e string B)PHG pluginTW*ormat_proc 5 Format%

++ pointer to a *unction t&at returns a descriptive ++ string *or t&e -itmap typeG For eample0 a plugin ++ t&at loads B)Ps may return 7indo;s or O#+? BitmapH

pluginTWdescription_proc 5 Description%

++ pointer to a *unction t&at returns a comma delimited ++ list o* possi-le *ile etension t&at are valid *or ++ t&is pluginG A ZP plugin ;ould return [peg0[i*0[*i*H

pluginTWetension_proc 5 tension%

++ pointer to a *unction t&at is used to load t&e -itmap

pluginTWload_proc 5 Load%

++ pointer to a *unction t&at is used to save t&e -itmap

pluginTWsave_proc 5 #ave%

++ pointer to a *unction t&at ;ill try to identi*y a++ -itmap -y loo

8/13/2019 Free Image 3151

55/129

!ultipage functions

FreeImage fea"ures a se" of func"ions "ha" can be used "o manipula"e pages in a mul"i:pagebi"map forma"! 3urren"ly TIFF, I3O and EIF forma"s are suppor"ed for "his! The mul"i:page(-I makes i" possible "o access and change pages in a mul"i:bi"map, dele"e pages andchange "he order of pages! (ll of "his is offered wi"h a minimum implemen"a"ion in a pluginand low reCuiremen" of memory "hrough a sophis"ica"ed, compressing cache mechanism!

In "he mul"ipage (-I, whene#er a \page' parame"er is needed by a func"ion, i" is always:based!

FreeImage-/pen!ultiitmap

DLL_API FI)!L"IBI")AP ' DLL_CALLCONV FreeImage_Open)ultiBitmap(F/_I)A_FO/)A" *i*0const c&ar '*ilename0 BOOL create_ne;0 BOOL read_only0 BOOL

8/13/2019 Free Image 3151

56/129

static unsigned DLL_CALLCONVmy/eadProc(void '-u**er0 unsigned sie0 unsigned count0 *i_&andle &andle$ 1 return (unsigned$*read(-u**er0 sie0 count0 (FIL '$&andle$%9

static unsigned DLL_CALLCONVmy7riteProc(void '-u**er0 unsigned sie0 unsigned count0 *i_&andle &andle$ 1 return (unsigned$*;rite(-u**er0 sie0 count0 (FIL '$&andle$%

9static int DLL_CALLCONVmy#ee

8/13/2019 Free Image 3151

57/129

BOOL test#tream)ultiPage#ave(const c&ar 'input0 const c&ar 'output0 int input_*lag0int output_*lag$ 1 ++ initialie your o;n IO *unctions

FreeImageIO io%

ioGread_proc 5 my/eadProc% ioG;rite_proc 5 my7riteProc%

ioGsee

8/13/2019 Free Image 3151

58/129

BOOL test#tream)ultiPageOpen#ave(const c&ar 'input0 const c&ar 'output0 intinput_*lag0 int output_*lag$ 1 ++ initialie your o;n IO *unctions

FreeImageIO io%

ioGread_proc 5 my/eadProc% ioG;rite_proc 5 my7riteProc%

ioGsee

8/13/2019 Free Image 3151

59/129

3loses a pre#iously opened mul"i:page bi"map and, when "he bi"map was no" opened read:only, applies any changes made "o i"!

The flags parame"er is used "o change "he beha#iour or enable a fea"ure in "he bi"map plugin!2ach plugin has i"s own se" of parame"ers )see Table ;*! Some bi"map sa#ers can recei#eparame"ers "o change "he sa#ing beha#iour! When "he parame"er is no" a#ailable or unusedyou can pass "he #alue or NTB-26OF6%ITM(-602F(7LT )e!g! TIFF602F(7LT,

I3O602F(7LT, e"c*!

FreeImage-et4ageCount

DLL_API int DLL_CALLCONV FreeImage_etPageCount(FI)!L"IBI")AP '-itmap$%

@e"urns "he number of pages curren"ly a#ailable in "he mul"i:paged bi"map!

FreeImage-(ppend4age

DLL_API void DLL_CALLCONV FreeImage_AppendPage(FI)!L"IBI")AP '-itmap0 FIBI")AP 'data$%

(ppends a new page "o "he end of "he bi"map!

FreeImage-Insert4age

DLL_API void DLL_CALLCONV FreeImage_InsertPage(FI)!L"IBI")AP '-itmap0 int page0FIBI")AP 'data$%

Inser"s a new page before "he gi#en posi"ion in "he bi"map! -age has "o be a number smaller"han "he curren" number of pages a#ailable in "he bi"map!

FreeImage-Delete4age

DLL_API void DLL_CALLCONV FreeImage_DeletePage(FI)!L"IBI")AP '-itmap0 int page$%

0ele"es "he page on "he gi#en posi"ion!

FreeImage-Loc%4age

DLL_API FIBI")AP ' DLL_CALLCONV FreeImage_Loc

8/13/2019 Free Image 3151

60/129

7nlocks a pre#iously locked page and gi#es i" back "o "he mul"i:page engine! When "he las"parame"er is T@72, "he page is marked changed and "he new page da"a is applied in "hemul"i:page bi"map!

-ool Clone)ultiPage(F/_I)A_FO/)A" *i*0 c&ar 'input0 c&ar 'output0 int output_*lag$1

BOOL -)emoryCac&e 5 "/!%

++ Open src *ile (readTonly0 use memory cac&e$ FI)!L"IBI")AP 'src 5 FreeImage_Open)ultiBitmap(*i*0 input0 FAL#0 "/!0-)emoryCac&e$%

i*(src$ 1 ++ Open dst *ile (creation0 use memory cac&e$ FI)!L"IBI")AP 'dst 5 FreeImage_Open)ultiBitmap(*i*0 output0 "/!0 FAL#0-)emoryCac&e$%

++ et src page count int count 5 FreeImage_etPageCount(src$%

++ Clone src to dst *or(int page 5 =% page count% page$ 1

++ Load t&e -itmap at position YpageY FIBI")AP 'di- 5 FreeImage_Loc

8/13/2019 Free Image 3151

61/129

!emory IG/ streams

Memory I8O rou"ines use a specialied #ersion of "he FreeImageIO s"ruc"ure, "arge"ed "osa#e8load FI%ITM(- images "o8from a memory s"ream! Jus" like you would do wi"h a files"ream! Memory file s"reams suppor" loading and sa#ing of FI%ITM(- in a memory file)managed in"ernally by FreeImage*! They also suppor" seeking and "elling in "he memory file!

2xamples of using "hese func"ions would be "o s"ore image files as blobs in a da"abase, or "owri"e image files "o a In"erne" s"ream!

FreeImage-/pen!emory

DLL_API FI))O/ 'DLL_CALLCONV FreeImage_Open)emory(B" 'data FI_DFA!L"(=$0 D7O/Dsie_in_-ytes FI_DFA!L"(=$$%

Open a memory s"ream! The func"ion re"urns a poin"er "o "he opened memory s"ream!

When called wi"h defaul" argumen"s )*, "his func"ion opens a memory s"ream for read 8 wri"eaccess! The s"ream will suppor" loading and sa#ing of FI%ITM(- in a memory file )managedin"ernally by FreeImage*! I" will also suppor" seeking and "elling in "he memory file!

This func"ion can also be used "o wrap a memory buffer pro#ided by "he applica"ion dri#ingFreeImage! ( buffer con"aining image da"a is gi#en as func"ion argumen"s data)s"ar" of "hebuffer* and si"e_in_ytes)buffer sie in by"es*! ( memory buffer wrapped by FreeImage isread only! Images can be loaded bu" canno" be sa#ed!

FreeImage-Close!emory

DLL_API void DLL_CALLCONV FreeImage_Close)emory(FI))O/ 'stream$%

3lose and free a memory s"ream!

When "he s"ream is managed by FreeImage, "he memory file is des"royed! O"herwise)wrapped buffer*, i"'s des"ruc"ion is lef" "o "he applica"ion dri#ing FreeImage!

Bou always need "o call "his func"ion once you're done wi"h a memory s"ream)wha"e#er "he way you opened "he s"ream*, or you will ha#e a memory leak!

FreeImage-LoadFrom!emory

DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_LoadFrom)emory(F/_I)A_FO/)A" *i*0FI))O/ 'stream0 int *lags FI_DFA!L"(=$$%

This func"ion does for memory s"reams wha" FreeImage6Load does for file s"reams!FreeImage6LoadFromMemory decodes a bi"map, alloca"es memory for i" and "hen re"urns i"as a FI%ITM(-! The firs" parame"er defines "he "ype of bi"map "o be loaded! For example,when FIF6%M- is passed, a %M- file is loaded in"o memory )an o#er#iew of possibleF@226IM(E26FO@M(T cons"an"s is a#ailable in Table $*! The second parame"er "ellsFreeImage "he memory s"ream i" has "o decode! The las" parame"er is used "o change "hebeha#iour or enable a fea"ure in "he bi"map plugin! 2ach plugin has i"s own se" of parame"ers!

Some bi"map loaders can recei#e parame"ers "o change "he loading beha#iour )see Table >*!When "he parame"er is no" a#ailable or unused you can pass "he #alue orNTB-26OF6%ITM(-602F(7LT )e!g! %M-602F(7LT, I3O602F(7LT, e"c*!

FreeImage 3.15.1 documentation (ppendi) 5"

8/13/2019 Free Image 3151

62/129

void testLoad)emIO(const c&ar 'lpsPat&Name$ 1 struct stat -u*% int result%

++ get data associated ;it& lpsPat&Name result 5 stat(lpsPat&Name0 -u*$% i*(result 55 =$ 1

++ allocate a memory -u**er and load temporary data B" 'mem_-u**er 5 (B"'$malloc(-u*Gst_sie ' sieo*(B"$$% i*(mem_-u**er$ 1 FIL 'stream 5 *open(lpsPat&Name0 2r-2$% i*(stream$ 1 *read(mem_-u**er0 sieo*(B"$0 -u*Gst_sie0 stream$% *close(stream$%

++ attac& t&e -inary data to a memory stream FI))O/ '&mem 5 FreeImage_Open)emory(mem_-u**er0 -u*Gst_sie$%

++ get t&e *ile type F/_I)A_FO/)A" *i* 5 FreeImage_etFile"ypeFrom)emory(&mem0 =$%

++ load an image *rom t&e memory stream FIBI")AP 'c&ec< 5 FreeImage_LoadFrom)emory(*i*0 &mem0 =$%

++ save as a regular *ile

FreeImage_#ave(FIF_PN0 c&ec

8/13/2019 Free Image 3151

63/129

void test#ave)emIO(const c&ar 'lpsPat&Name$ 1 FI))O/ '&mem 5 N!LL%

++ load and decode a regular *ile F/_I)A_FO/)A" *i* 5 FreeImage_etFile"ype(lpsPat&Name$% FIBI")AP 'di- 5 FreeImage_Load(*i*0 lpsPat&Name0 =$%

++ open a memory stream &mem 5 FreeImage_Open)emory($%

++ encode and save t&e image to t&e memory FreeImage_#ave"o)emory(*i*0 di-0 &mem0 =$%

++ at t&is point0 &mem contains t&e entire data in memory stored in *i* *ormatG++ t&e amount o* space used -y t&e memory is eUual to *ile_sie

long *ile_sie 5 FreeImage_"ell)emory(&mem$% print*(2File sie X 8ld3n20 *ile_sie$%

++ its easy to load an image *rom memory as ;ell

++ see< to t&e start o* t&e memory stream FreeImage_#ee

8/13/2019 Free Image 3151

64/129

void testAcUuire)emIO(const c&ar 'lpsPat&Name$ 1 FI))O/ '&mem 5 N!LL%

++ load a regular *ile F/_I)A_FO/)A" *i* 5 FreeImage_etFile"ype(lpsPat&Name$% FIBI")AP 'di- 5 FreeImage_Load(*i*0 lpsPat&Name0 =$%

++ open and allocate a memory stream &mem 5 FreeImage_Open)emory($%

++ save t&e image to a memory stream FreeImage_#ave"o)emory(FIF_PN0 di-0 &mem0 PN_DFA!L"$%

FreeImage_!nload(di-$%

++ get t&e -u**er *rom t&e memory stream B" 'mem_-u**er 5 N!LL% D7O/D sie_in_-ytes 5 =%

FreeImage_AcUuire)emory(&mem0 mem_-u**er0 sie_in_-ytes$%

++ save t&e -u**er to a *ile stream FIL 'stream 5 *open(2-u**erGpng20 2;-2$% i*(stream$ 1 *;rite(mem_-u**er0 sieo*(B"$0 sie_in_-ytes0 stream$%

*close(stream$% 9

++ close an$ f!ee t%e "e"o!y st!ea" FreeImage_Close)emory(&mem$%

9

FreeImage-$ell!emory

DLL_API long DLL_CALLCONV FreeImage_"ell)emory(FI))O/ 'stream$%

Ee"s "he curren" posi"ion of a memory poin"er! 7pon en"ry, stream is "he "arge" memorys"ream! The func"ion re"urns "he curren" file posi"ion if successful, :$ o"herwise!

FreeImage-0ee%!emory

DLL_API BOOL DLL_CALLCONV FreeImage_#ee

8/13/2019 Free Image 3151

65/129

FreeImage-+ead!emory

DLL_API unsigned DLL_CALLCONV FreeImage_/ead)emory(void '-u**er0 unsigned sie0unsigned count0 FI))O/ 'stream$%

@eads da"a from a memory s"ream!

The FreeImage6@eadMemory func"ion reads up "o counti"ems of si"eby"es from "he inpu"memory s"ream and s"ores "hem in uffer! The memory poin"er associa"ed wi"h stream isincreased by "he number of by"es ac"ually read!

The func"ion re"urns "he number of full i"ems ac"ually read, which may be less "han countif anerror occurs or if "he end of "he s"ream is encoun"ered before reaching count!

FreeImage-Erite!emory

DLL_API unsigned DLL_CALLCONV FreeImage_7rite)emory(const void '-u**er0 unsigned sie0unsigned count0 FI))O/ 'stream$%

Wri"es da"a "o a memory s"ream!

The FreeImage6Wri"eMemory func"ion wri"es up "o count i"ems, of si"e leng"h each, fromuffer "o "he ou"pu" memory s"ream! The memory poin"er associa"ed wi"h stream isincremen"ed by "he number of by"es ac"ually wri""en!

The func"ion re"urns "he number of full i"ems ac"ually wri""en, which may be less "han countifan error occurs!

FreeImage_%ead,emory and FreeImage_Write,emory are useful whene#er youneed a memory s"ream "o s"ore "emporary da"a! When combined wi"hFreeImage_$ee!,emory and FreeImage_-ell,emory, "his represen"s an al"erna"i#e

"o "he use of "emporary files!

FreeImage-Load!ultiitmapFrom!emory

DLL_API FI)!L"IBI")AP 'DLL_CALLCONVFreeImage_Load)ultiBitmapFrom)emory(F/_I)A_FO/)A" *i*0 FI))O/ 'stream0 int *lagsFI_DFA!L"(=$$%

Open a mul"i:page bi"map from a memory s"ream!

This func"ion is similar "o "he FreeImage6OpenMul"i%i"mapfunc"ion, wi"h "he difference "ha"you will be able "o open a mul"i:page file, in readonly mode, from a memory s"ream ins"ead of

a file s"ream!

The firs" parame"er "ells FreeImage "he bi"map:"ype of bi"map "o be opened! 3urren"lyFIF6TIFF, FIF6I3O and FIF6EIF are suppor"ed! The second parame"er "ells FreeImage "hememory s"ream i" has "o decode! The las" parame"er is used "o change "he beha#iour orenable a fea"ure in "he bi"map plugin! 2ach plugin has i"s own se" of parame"ers!

(l"ough "he source memory handle is opened in read:only mode, using "his func"ion, mul"i:page memory handles suppor" read or read8wri"e opera"ions! When you modify a mul"i:pagefile using func"ions such as FreeImage6(ppend-age, FreeImage6Inser"-age,FreeImage6Mo#e-age or FreeImage60ele"e-age, changes are "ransparen"ly s"ored in"o amemory cache so "ha" "hese changes can be la"er sa#ed "o an ou"pu" s"ream! The sourcememory s"ream is lef" unmodified1 closing "he source s"ream will no" change i"! Bou "hus need"o use a kind of sa#e as HG func"ion "o sa#e your changes!


8/13/2019 Free Image 3151

66/129

static BOOLetractPagesFrom)emory(F/_I)A_FO/)A" *i*0 FI))O/ 'stream$ 1 c&ar *ilename?EQ% ++ open t&e multipage -itmap stream as readTonly FI,#L-I.I-,AP s!c = F!eeI"age_Loa$,ulti.it"apF!o",e"o!y(fif) st!ea") 0*; i*(src$ 1 ++ get t&e page count

int count 5 FreeImage_etPageCount(src$% ++ etract all pages *or(int page 5 =% page count% page$ 1 ++ load t&e -itmap at position YpageY FIBI")AP 'di- 5 FreeImage_Loc

8/13/2019 Free Image 3151

67/129

BOOL test#ave)ultiBitmap"o)emory(const c&ar 'input0 const c&ar 'output0 intoutput_*lag$ 1 BOOL -#uccess%

BOOL -CreateNe; 5 FAL#% BOOL -/eadOnly 5 "/!% BOOL -)emoryCac&e 5 "/!%

++ Open src *ile (readTonly0 use memory cac&e$ F/_I)A_FO/)A" *i* 5 FreeImage_etFile"ype(input$% FI)!L"IBI")AP 'src 5 FreeImage_Open)ultiBitmap(*i*0 input0 -CreateNe;0 -/eadOnly0-)emoryCac&e$%

i*(src$ 1 ++ open and allocate a memory stream FI))O/ 'dst_memory 5 FreeImage_Open)emory($%

++ save t&e *ile to memory &Success = F!eeI"age_Sae,ulti.it"ap-o,e"o!y(fif) s!c) $st_"e"o!y) output_flag*; assert(-#uccess$%

++ src is no longer neededX close and *ree src *ile FreeImage_Close)ultiBitmap(src0 =$%

++ get t&e -u**er *rom t&e memory stream

B" 'mem_-u**er 5 N!LL% D7O/D sie_in_-ytes 5 =%

-#uccess 5 FreeImage_AcUuire)emory(dst_memory0 mem_-u**er0 sie_in_-ytes$% assert(-#uccess$%

++ save t&e -u**er in a *ile stream FIL 'stream 5 *open(output0 2;-2$% i*(stream$ 1 *;rite(mem_-u**er0 sieo*(B"$0 sie_in_-ytes0 stream$% *close(stream$% 9

++ close and *ree t&e memory stream FreeImage_Close)emory(dst_memory$%

return "/!%

9

return FAL#%9

The following sample shows how "o modify an inpu" memory s"ream and sa#e yourmodifica"ions in"o an ou"pu" memory s"ream! Do"e "ha" "he inpu" s"ream is lef" unchanged1 allmodifica"ions are s"ored in"o a cache "his cache is "hen used "o apply your modifica"ion onsa#ing!


8/13/2019 Free Image 3151

68/129

static BOOLloadBu**er(const c&ar 'lpsPat&Name0 B" ''-u**er0 D7O/D 'lengt&$ 1 struct stat *ile_in*o% int result%

++ get data associated ;it& lpsPat&Name result 5 stat(lpsPat&Name0 *ile_in*o$%

i*(result 55 =$ 1 ++ allocate a memory -u**er and load temporary data '-u**er 5 (B"'$malloc(*ile_in*oGst_sie ' sieo*(B"$$% i*('-u**er$ 1 FIL 'stream 5 *open(lpsPat&Name0 2r-2$% i*(stream$ 1 'lengt& 5 (D7O/D$*read('-u**er0 sieo*(B"$0 *ile_in*oGst_sie0 stream$% *close(stream$%

return "/!% 9 9 9

return FAL#%9

BOOL test)emory#tream)ultiPageOpen#ave(const c&ar 'lpsPat&Name0 c&ar 'output0 int

input_*lag0 int output_*lag$ 1 BOOL -#uccess 5 FAL#%

B" '-u**er 5 N!LL% D7O/D -u**er_sie 5 =%

++ load source stream as a -u**er0 iGeG++ allocate a memory -u**er and load temporary data

-#uccess 5 loadBu**er(lpsPat&Name0 -u**er0 -u**er_sie$% assert(-#uccess$%

++ attac& t&e -inary data to a memory stream FI))O/ 'src_stream 5 FreeImage_Open)emory(-u**er0 -u**er_sie$% assert(src_stream$%

++ open t&e multipage -itmap stream F/_I)A_FO/)A" *i* 5 FreeImage_etFile"ypeFrom)emory(src_stream0 =$%

FI)!L"IBI")AP 'src 5 FreeImage_Load)ultiBitmapFrom)emory(*i*0 src_stream0input_*lag$%

++ apply some modi*ications (everyt&ing -eing stored to t&e cac&e$ GGG

i*(src$ 1 ++ get t&e page count int count 5 FreeImage_etPageCount(src$% assert(count W ?$%

++ Load t&e -itmap at position Y?Y FIBI")AP 'di- 5 FreeImage_Loc

8/13/2019 Free Image 3151

69/129

++ save t&e *ile to memory

FreeImage_#ave)ultiBitmap"o)emory(*i*0 src0 dst_stream0 output_*lag$%

++ src is no longer needed ++ close and *ree t&e memory stream FreeImage_Close)emory(src_stream$% // close an$ f!ee s!c file (not%ing is $one) t%e cac%e is clea!e$*

FreeImage_Close)ultiBitmap(src0 =$% ++ at t&is point0 t&e input -u**er is no longer needed // 222 use! is !esponsi&le fo! f!eeing t%e initial sou!ce &uffe! 222 *ree(-u**er$% -u**er 5 N!LL%

++ get t&e dst -u**er *rom t&e memory stream B" 'dst_-u**er 5 N!LL% D7O/D sie_in_-ytes 5 =%

FreeImage_AcUuire)emory(dst_stream0 dst_-u**er0 sie_in_-ytes$%

++ save t&e -u**er in a *ile stream FIL 'stream 5 *open(output0 2;-2$% i*(stream$ 1 *;rite(dst_-u**er0 sieo*(B"$0 sie_in_-ytes0 stream$% *close(stream$% 9

++ close and *ree t&e memory stream

FreeImage_Close)emory(dst_stream$%

return "/!% 9

i*(-u**er$ 1 *ree(-u**er$% 9

return FAL#%9


8/13/2019 Free Image 3151

70/129

Compression functions

FreeImage uses many Open Source "hird par"y libraries in order "o load or sa#e compleximage file forma"s! (mong "hese libraries, some of "hem, such as "he KLib library, deal wi"hcompression 8 decompression of memory buffers! Since "his fea"ure may be useful in manyapplica"ions and no" only for image compression, FreeImage pro#ides an in"erface "o "hemain func"ionali"ies of "hese libraries!

3urren"ly, only KLib compression is suppor"ed! O"her compression algori"hms may be addedwi"h fu"ure releases of FreeImage!

FreeImage-;LibCompress

DLL_API D7O/D DLL_CALLCONV FreeImage_]Li-Compress(B" 'target0 D7O/D target_sie0B" 'source0 D7O/D source_sie$%

3ompresses a source buffer in"o a "arge" buffer, using "he KLib library! 7pon en"ry,"arge"6sie is "he "o"al sie of "he des"ina"ion buffer, which mus" be a" leas" !$ larger "hansource6sie plus $+ by"es!

The func"ion re"urns "he ac"ual sie of "he compressed buffer, or re"urns if an erroroccurred!

B" 'data 5 N!LL%D7O/D original_sie 5 =%++ GGGdata 5 (B"'$malloc(original_sie ' sieo*(B"$$%++ GGG

++ compress dataD7O/D compressed_sie 5 (D7O/D$((dou-le$ original_sie (=G ' (dou-le$

original_sie$ ?$%B" 'compressed_data 5 (B"'$malloc(compressed_sie ' sieo*(B"$$%compressed_sie 5 FreeImage_]Li-Compress(compressed_data0 compressed_sie0 data0original_sie$%

++ ;rite data to dis, "oge"her wi"h"he FreeImage plugins "ha" can load or sa#e "he corresponding me"ada"a!

These me"ada"a models are described in more de"ail in "he appendix )see FreeImageme"ada"a models*!

FreeImage 3.15.1 documentation (ppendi) "1

8/13/2019 Free Image 3151

76/129

!etadata model G FIF FIF-?4 FIF-$IFF FIF-4: FIF-IF FIF-+(E

# FI!D-C/!!:$0 @8W : @8W @8W :

1 FI!D-IF-!(I: @ @ : : @

' FI!D-IF-IF @ @ : : @

3 FI!D-IF-40 @ : : : @

FI!D-IF-!(J+:/$ @ : : : @

5 FI!D-IF-I:$+/4 @ : : : @

6 FI!D-I4$C @8W @8W : : :

" FI!D-!4 @8W @8W @8W : :

& FI!D-/$IFF : @8W : : :

= FI!D-(:I!($I/: : : : @8W :

1# FI!D-C90$/! : : : : :

11 FI!D-IF-+(E @8W : : : :

+ @ead, E Wri"e, 7 Do" implemen"ed

$able 13* !etadata models supported by FreeImage.

"' (ppendi) FreeImage 3.15.1 documentation

8/13/2019 Free Image 3151

77/129

$ag creation and destruction

FreeImage-Create$agDLL_API FI"A 'DLL_CALLCONV FreeImage_Create"ag($%

(lloca"es a new FIT(E ob&ec"! This ob&ec" mus" be des"royed wi"h a call "oFreeImage60ele"eTag when no longer in use!

Tag crea"ion and des"ruc"ion func"ions are only needed when you use "heFreeImage6Se"Me"ada"afunc"ion!

FreeImage-Delete$ag

DLL_API void DLL_CALLCONV FreeImage_Delete"ag(FI"A 'tag$%

0ele"e a pre#iously alloca"ed FIT(E ob&ec"!

FreeImage-Clone$ag

DLL_API FI"A 'DLL_CALLCONV FreeImage_Clone"ag(FI"A 'tag$%

3rea"es and re"urns a copy of a FIT(E ob&ec"! This copy mus" be des"royed wi"h a call "oFreeImage60ele"eTag when no longer in use!

FreeImage 3.15.1 documentation (ppendi) "3

8/13/2019 Free Image 3151

78/129

$ag accessors

FreeImage-et$agJeyDLL_API const c&ar 'DLL_CALLCONV FreeImage_et"ag6ey(FI"A 'tag$%

@e"urns "he "ag field name )uniCue inside a me"ada"a model*!

FreeImage-et$agDescription

DLL_API const c&ar 'DLL_CALLCONV FreeImage_et"agDescription(FI"A 'tag$%

@e"urns "he "ag descrip"ion if a#ailable, re"urns D7LL o"herwise!

FreeImage-et$agID

DLL_API 7O/D DLL_CALLCONV FreeImage_et"agID(FI"A 'tag$%

@e"urns "he "ag I0 if a#ailable, re"urns o"herwise!

FreeImage-et$ag$ype

DLL_API F/_I)A_)D"P DLL_CALLCONV FreeImage_et"ag"ype(FI"A 'tag$%

@e"urns "he "ag da"a "ype )see Table $+for a lis" of known da"a "ypes*!

FreeImage-et$agCount

DLL_API D7O/D DLL_CALLCONV FreeImage_et"agCount(FI"A 'tag$%

@e"urns "he number of componen"s in "he "ag )in tag typeuni"s*! For example, when "he "agda"a "ype indica"es a double )i!e! a FI0T60O7%L2 "ype* and "he "ag coun" is

8/13/2019 Free Image 3151

79/129

FreeImage-0et$agJey

DLL_API BOOL DLL_CALLCONV FreeImage_#et"ag6ey(FI"A 'tag0 const c&ar '

8/13/2019 Free Image 3151

80/129

FreeImage-0et$agalue

DLL_API BOOL DLL_CALLCONV FreeImage_#et"agValue(FI"A 'tag0 const void 'value$%

Se" "he "ag #alue )al>ays reHuired*! The func"ion re"urns T@72 if successful and re"urnsF(LS2 o"herwise!

This func"ion mus" be called after"he "ag da"a "ype, "ag coun" and "ag leng"h ha#ebeen filled! O"herwise, you will be unable "o successfully call FreeImage6Se"Me"ada"a!

"6 (ppendi) FreeImage 3.15.1 documentation

Documents

Free Image 3151