Free Image 3151

FreeImage
a free, open source graphics library
Documentation Library version 3.15.1
Contents
Introduction 1
Foreword...............................................................................................................................1 Purpose of FreeImage...........................................................................................................1 Library reference..................................................................................................................2
itmap function reference
General functions..................................................................................................................3 Bitmap management functions.............................................................................................5 Bitmap information functions.............................................................................................13 Filetype functions............................................................................................................... 23 Pi el 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......................................................................................,* Bac1ground filling............................................................................................................1-1 &iscellaneous algorit.ms.................................................................................................1-*
(ppendi)
1#"
2upported file formats......................................................................................................1-) 2upported camera /34 file formats............................................................................... 1-$ !.oosing t.e rig.t resampling filter.................................................................................1-, 0sing t.e rotation functions..............................................................................................113 FreeImage metadata models.............................................................................................11* FI&5637I&3#I(7 metadata model specification....................................................... 12-
FreeImage 3.15.1 documentation
Contents i
List of tables
$able 1* F+,,-I!(.,-F/+!($0 constants 1FreeImage format identifiers2. $able '* F+,,-I!(.,-$34, constants 1FreeImage data type identifiers2. $able 3* /ptionnal decoder constants. $able 5* /ptionnal encoder constants. $able 5* F+,,-I!(.,-C/L/+-$34, constants. 5
" & 11 16
$able 6* 4i)el access macros and associated mas%s for '57 or 3'7bit images. '6 $able "* F+,,-I!(.,-89(:$I;, constants. $able &* F+,,-I!(.,-DI$<,+ constants. $able =* itmap type conversions allo>ed by FreeImage. 3' 35 36 3& "#
$able 1#* F+,,-I!(.,-$!/ constants. $able 11* FreeImage FI$(. structure. $able 1'* FreeImage tag data types 1F+,,-I!(.,-!D$34, identifier2. $able 13* !etadata models supported by FreeImage. $able 15* F+,,-I!(.,-?4,.-/4,+($I/: constants. $able 15* I!(.,-FIL$,+ constants. $able 16* F+,,-I!(.,-C/L/+-C<(::,L constants. $able 1"* $able 1&* ac%ground filling options for '57 or 3'7bit images ac%ground filling options for palleti@ed images
"1 "' &5 &6 &= 1#1 1#'
ii List of figures
$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 image resi@ed to 5##A. 11# Figure 3* Comparison of resampling filters on a 5#)56 resi@ed to &##A. i%ini image 11' 113 113
Figure 5* 4arrot image rotated by 55B using FreeImage-+otate. Figure 5* 4arrot image rotated by =#B using FreeImage-+otate.
Figure 6* 0ome e)amples illustrating the use of FreeImage-+otate,). 115
Contents iii
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" has been 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"map loading 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 "o FreeImage, adding new fea"ures and helping "o "es" "he library! Wi"hou" "he help of "hese people, FreeImage wouldn'" ha#e been where i" is now! (nyone can con"ribu"e and pos" "heir changes and impro#emen"s and ha#e "hem inser"ed in "he main sources )of course on "he condi"ion "ha" de#elopers agree on "ha" "he fixes are good*! The lis" of con"ribu"ors in "he changelog 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 which fea"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 (d#anced image processing opera"ions such as con#olu"ion and "ransforms %i"map drawing 4ec"or graphics
FreeImage does no" suppor"1

(ppendi) 1
Library reference
2ach func"ion name in FreeImage s"ar"s wi"h 5FreeImage65, FreeImage6Load, FreeImage6Sa#e, FreeImage67nload !!! for ins"ance ( 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 reference chap"ers! For each en"ry, "he func"ion pro"o"ype is shown for 38399 and "he func"ion argumen"s and explana"ions are lis"ed! Throughou" "hese chap"ers, you will see numbers in colored boxes a" "he "op of some func"ions! These numbers indica"e "he pixel dep"h of "he inpu" image "ha" "he func"ion can opera"e on! This may be1 $:, ;:, <:, $=:, +;:, >+:bi" per pixel for standard bitmap )green boxes*, $=:, ;<:, =;:bi" per pixel for 9I:$16, +. 16 and +. (16 image types )blue boxes*, >+:, ?=:, $+<:bi" per pixel for FL/($, +. F and +. (F image types )orange 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 image pixel dep"h )e!g! for load 8 sa#e and plugins func"ions*!
' (ppendi)
itmap function reference
.eneral functions
The following func"ions don'" ha#e any"hing "o do wi"h "he bi"map suppor" pro#ided by FreeImage! 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_only FI_D FA!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 "he load6local6plugins6only parame"er se" "o F(LS2! When using FreeImage as a s"a"ic linked library, you mus" call "his func"ion e)actly once a" "he s"ar" of your program!
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 once a" "he end 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 call FreeImage6Ini"ialise a" "he beginning of your main func"ion and you need "o call FreeImage60eIni"ialise a" "he end of "his main func"ion )"his is no" needed when using FreeImage as a !SO*!
(ppendi) 3
FreeImage-.etCersion
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"! For example a cer"ain bi"map forma" migh" no" be suppor"ed due "o pa"en" res"ric"ions, or "here migh" be a known issue wi"h a cer"ain bi"map sub"ype! Whene#er some"hing fails in FreeImage in"ernally a log:s"ring is genera"ed, which can be cap"ured by an applica"ion dri#ing FreeImage! 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 FreeImage rror.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(FreeImage rror.andler$%
The fif parame"er passed in "he callback firs" argumen" may be eCual "o FIF_UNKNOWN when 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 F printf()G may crash your applica"ion so &us" be careful H
5 (ppendi)
itmap management functions

The bi"map managemen" func"ions in FreeImage are defini"ely "he mos" used ones! They allow you "o alloca"e new bi"maps, impor" bi"maps so "ha" "hey can be edi"ed in memory and expor" bi"maps "o disc! (s you will see, "he FreeImage bi"map managemen" func"ions are #ery easy "o use! (l"hough FreeImage can handle more "han +, bi"map "ypes, "here are only ; bi"map handling func"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 file F@22IM(E2!.! The following F@226IM(E26FO@M(TS cons"an"s are curren"ly a#ailable1 FIF
FIF67DIDOWD FIF6%MFIF637T FIF600S FIF62 @ FIF6F( E> FIF6EIF FIF6.0@ FIF6I3O FIF6IFF FIF6J+I FIF6JDE FIF6J-+ FIF6J-2E FIF6IO(L( FIF6MDE FIF6-%M FIF6-%M@(W FIF6-30 FIF6-3 FIF6-FM FIF6-EM FIF6-EM@(W FIF6-I3T FIF6-DE FIF6--M FIF6--M@(W FIF6-S0 FIF6@(S FIF6@(W FIF6SEI FIF6T(@E( FIF6TIFF FIF6W%MFIF6 %M FIF6 -M
Description
7nknown forma" )returned value only, never use it as input value* Windows or OS8+ %i"map File )A!%M-* 0r! .alo )A!37T* 0irec"0raw Surface )A!00S* ILM Open2 @ )A!2 @* @aw Fax forma" 33ITT E> )A!E>* Eraphics In"erchange Forma" )A!EIF* .igh 0ynamic @ange )A!.0@* Windows Icon )A!I3O* (miga IFF )A!IFF, A!L%M* J-2E:+,,, codes"ream )A!J+I, A!J+3* J-2E De"work Eraphics )A!JDE* J-2E:+,,, File Forma" )A!J-+* Independen" J-2E Eroup )A!J-E, A!JIF, A!J-2E, A!J-2* 3ommodore =; Ioala forma" )A!IO(* Mul"iple De"work Eraphics )A!MDE* -or"able %i"map )(S3II* )A!-%M* -or"able %i"map )%ID(@B* )A!-%M* Iodak -ho"o30 )A!-30* Ksof" -ain"brush -3 bi"map forma" )A!-3 * -or"able Floa"map )A!-FM* -or"able Eraymap )(S3II* )A!-EM* -or"able Eraymap )%ID(@B* )A!-EM* Macin"osh -I3T )A!-3T, A!-I3T, A!-I3* -or"able De"work Eraphics )A!-DE* -or"able -ixelmap )(S3II* )A!--M* -or"able -ixelmap )%ID(@B* )A!--M* (dobe -ho"oshop )A!-S0* Sun @as"erfile )A!@(S* @(W camera image )many extensions* Silicon Eraphics SEI image forma" )A!SEI* True#ision Targa files )A!TE(, A!T(@E(* Tagged Image File Forma" )A!TIF, A!TIFF* Wireless %i"map )A!W%M-* $$ %i"map Forma" )A! %M* $$ -ixmap Forma" )A! -M*
$able 1* F+,,-I!(.,-F/+!($0 constants 1FreeImage format identifiers2.
(ppendi) 5
(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"map plugin 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 -pp0 unsigned red_mas< FI_D FA!L"(=$0 unsigned green_mas< FI_D FA!L"(=$0 unsigned -lue_mas< FI_D FA!L"(=$$%
If you wan" "o crea"e a new bi"map in memory from scra"ch, wi"hou" loading a pre:made bi"map from disc, you use "his func"ion! FreeImage6(lloca"e "akes a wid"h and heigh" parame"er, and a bpp parame"er "o specify "he bi" dep"h of "he image and re"urns a FI%ITM(-! The op"ional las" "hree parame"ers )red6mask, green6mask and blue6mask* are used "o "ell FreeImage "he bi":layou" of "he color componen"s in "he bi"map, e!g! where in a pixel "he red, green and blue componen"s are s"ored! To gi#e you an idea abou" how "o in"erpre" "he color masks1 when red6mask is ,xFF,,,,,, "his means "ha" "he las" < bi"s in one pixel are used for "he color red! When green6mask is ,x,,,,,,FF, i" means "ha" "he firs" < bi"s in a pixel are used for "he color green! FreeImage6(lloca"e alloca"es an empty bi"map, e!g! a bi"map "ha" is filled comple"ely wi"h Leroes! Kero in a bi"map is usually in"erpre"ed as black! This means "ha" if your bi"map is palle"ised i" will con"ain a comple"ely black pale""e! Bou can access, and hence popula"e "he pale""e by using "he func"ion FreeImage6Ee"-ale""e! For <:bi" images only, FreeImage6(lloca"e will build a defaul" greyscale pale""e!
FIBI")AP '-itmap 5 FreeImage_Allocate(>?=0 ?@=0 >?$% i* (-itmap$ 1 ++ -itmap success*ully created4 9 FreeImage_!nload(-itmap$%
FreeImage6(lloca"e is an alias for FreeImage6(lloca"eT and can be replaced by "his call1 FreeImage6(lloca"eT)FIT6%ITM(-, wid"h, heigh", bpp, red6mask, green6mask, blue6mask*M
FreeImage-(llocate$
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Allocate"(F/ _I)A( _"AP type0 int ;idt&0 int &eig&t0 int -pp FI_D FA!L"(B$0 unsigned red_mas< FI_D FA!L"(=$0 unsigned green_mas< FI_D FA!L"(=$0 unsigned -lue_mas< FI_D FA!L"(=$$%
While mos" imaging applica"ions only deal wi"h pho"ographic images, many scien"ific applica"ions need "o deal wi"h high resolu"ion images )e!g! $=:bi" greyscale images*, wi"h real #alued pixels or e#en wi"h complex pixels )"hink for example abou" "he resul" of a Fas" Fourier Transform applied "o a <:bi" greyscale image1 "he resul" is a complex image*! ( special parame"er, an enum named F@226IM(E26TB-2, is used "o specify "he bi"map "ype of a FI%ITM(-! This enum is defined in "he header file F@22IM(E2!.! The following F@226IM(E26TB-2 cons"an"s are curren"ly a#ailable1
6 (ppendi)
FI$
FIT67DIDOWD FIT6%ITM(FIT67IDT$= FIT6IDT$= FIT67IDT>+ FIT6IDT>+ FIT6FLO(T FIT60O7%L2 FIT63OM-L2 FIT6@E%$= FIT6@E%($= FIT6@E%F FIT6@E%(F
Description
7nknown forma" )returned value only, never use it as input value * S"andard image1 $:, ;:, <:, $=:, +;:, >+:bi" (rray of unsigned shor"1 unsigned $=:bi" (rray of shor"1 signed $=:bi" (rray of unsigned long1 unsigned >+:bi" (rray of long1 signed >+:bi" (rray of floa"1 >+:bi" I222 floa"ing poin" (rray of double1 =;:bi" I222 floa"ing poin" (rray of FI3OM-L2 1 + x =;:bi" I222 floa"ing poin" ;<:bi" @E% image1 > x $=:bi" =;:bi" @E%( image1 ; x $=:bi" ?=:bi" @E% floa" image1 > x >+:bi" I222 floa"ing poin" $+<:bi" @E%( floa" image1 ; x >+:bi" I222 floa"ing poin"
$able '* F+,,-I!(.,-$34, constants 1FreeImage data type identifiers2. When you need "o know "he da"a "ype of a bi"map, you can use "he FreeImage6Ee"ImageType func"ion!
FIBI")AP '-itmap 5 FreeImage_Allocate"(FI"_/(BCD0 EC?0 EC?$% i* (-itmap$ 1 ++ -itmap success*ully created4 9 FreeImage_!nload(-itmap$%
FreeImage-Load
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Load(F/ '*ilename0 int *lags FI_D FA!L"(=$$% _I)A( _FO/)A" *i*0 const c&ar
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- is passed, a %M- file is loaded in"o memory )an o#er#iew of possible F@226IM(E26FO@M(T cons"an"s is a#ailable in Table $*! The second parame"er "ells FreeImage "he file i" has "o decode! 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 Fmy-itmapG-mpH0 B)P_D FA!L"$% i* (-itmap$ 1 ++ -itmap success*ully loaded4 9 FreeImage_!nload(-itmap$%
Some bi"map loaders can recei#e parame"ers "o change "he loading beha#iour! When "he parame"er is no" a#ailable or unused you can pass "he #alue , or NTB-26OF6%ITM(-O602F(7LT )e!g! %M-602F(7LT, I3O602F(7LT, e"c*!
(ppendi) "
itmap type
Nany typeO EIF
Flag
FIF6LO(06DO-I 2LS EIF602F(7LT EIF6LO(0+P= EIF6-L(B%(3I
Description
When "his flag is suppor"ed by a plugin, load only header da"a and possibly me"ada"a )including embedded "humbnail* )$* Load "he image as a +P= color image wi"h unused pale""e en"ries, if i"Qs $= or + color Q-layQ "he EIF "o genera"e each frame )as >+bpp* ins"ead of re"urning raw frame da"a when loading 3on#er" "o >+:bi" and crea"e an alpha channel from "he (D0: mask when loading Load "he file as fas" as possible, sacrificing some Cuali"y Load "he file as fas" as possible, sacrificing some Cuali"y Load "he file wi"h "he bes" Cuali"y, sacrificing some speed This flag will load 3MBI bi"maps as >+:bi" separa"ed 3MBI )use R "o combine wi"h o"her load flags*
I3O J-2E
I3O6M(I2(L-.( J-2E602F(7LT J-2E6F(ST J-2E6(337@(T2 J-2E63MBI
In"eger such "ha" flags S Load and resiLe "he file such "ha" siLe8 S max)wid"h, heigh"*8 flags R ) NN $=* will re"urn an image scaled by +, ; or < )i!e! "he mos" appropria"e reCues"ed siLe*! )+* J-2E62 IF@OT(T2 -30 -30602F(7LT -306%(S2 -306%(S20I4; -306%(S20I4$= -DE -S0 -DE6IEDO@2E(MM( -S0602F(7LT -S063MBI -S06L(% @(W @(W602F(7LT @(W6-@24I2W @(W60IS-L(B @(W6.(LFSIK2 T(@E( TIFF T(@E(6LO(06@E%<<< TIFF63MBI Load and ro"a"e according "o 2xif QOrien"a"ionQ "ag if a#ailable ( -ho"o30 pic"ure comes in many siLes! This flag will load "he one siLed T=< x P$+ This flag will load "he one siLed T=< x P$+ This flag will load "he bi"map siLed ><; x +P= This flag will load "he bi"map siLed $?+ x $+< (#oid gamma correc"ion Load and con#er" "o @E%U(V @eads "ags for separa"ed 3MBI )defaul" is con#ersion "o @E%* @eads "ags for 3I2Lab )defaul" is con#ersion "o @E%* Load "he file as linear @E% ;<:bi" Try "o load "he embedded J-2E pre#iew wi"h included 2xif da"a or defaul" "o @E% +;:bi" Load "he file as @E% +;:bi" Ou"pu" a half:siLe color image If se" "he loader con#er"s @E%PPP and (@E%<<<< :O @E%<<< This flag will load 3MBI bi"maps as separa"ed 3MBI )defaul" is con#ersion "o @E%*
$able 3* /ptionnal decoder constants.

)$* )+*
See "he FreeImage6.as-ixels sample code for a sample use! See "he FreeImage6MakeThumbnail sample code for a sample use!
Ins"ead of hardcoding "he F@226IM(E26FO@M(T when calling FreeImage6Load, i" is ad#ised "o use one of "he FreeImage File"ype func"ions such as FreeImage6Ee"FileType in order "o wri"e a generic code, independen" of possible fu"ure (-I changes!
FreeImage-Load9
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Load!(F/ '*ilename0 int *lags FI_D FA!L"(=$$% _I)A( _FO/)A" *i*0 const ;c&ar_t
& (ppendi)
This func"ion works exac"ly like FreeImage6Load 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"ion does no"hing and re"urns D7LL!
FreeImage-LoadFrom<andle
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_LoadFrom.andle(F/ _I)A( _FO/)A" *i*0 FreeImageIO 'io0 *i_&andle &andle0 int *lags FI_D FA!L"(=$$%
FreeImage has "he uniCue fea"ure "o load a bi"map from an arbi"rary source! This source migh" for example be a cabine" file, a Lip file or an In"erne" s"ream! .andling of "hese arbi"rary sources is no" direc"ly handled in "he F@22IM(E2!0LL, bu" can be easily added by using a FreeImageIO s"ruc"ure as defined in F@22IM(E2!.! FreeImageIO is a s"ruc"ure "ha" con"ains ; func"ion poin"ers1 one "o read from a source, one "o rite "o a source, one "o see! in "he source and one "o tell where in "he source we curren"ly are! When you popula"e "he FreeImageIO s"ruc"ure wi"h poin"ers "o func"ions and pass "ha" s"ruc"ure "o FreeImage6LoadFrom.andle, FreeImage will call your func"ions "o read, seek and "ell in a file! The handle:parame"er )"hird parame"er from "he lef"* is used in "his "o differen"ia"e be"ween differen" con"ex"s, e!g! differen" files or differen" In"erne" s"reams!
The func"ion poin"ers in FreeImageIO use "he s"dcall calling con#en"ion! This means "ha" "he func"ions poin"ed "o mus" also use "he s"dcall calling con#en"ion! The calling con#en"ion was chosen "o be compa"ible wi"h programming language o"her "han 399, such as 4isual %asic!
FreeImageIO io% ioGread_proc 5 /eadProc% ioG;rite_proc 5 N!LL% ioGsee<_proc 5 #ee<Proc% ioGtell_proc 5 "ellProc% FIL
++ ++ ++ ++
pointer to not needed pointer to pointer to
*unction t&at calls *read *or loading *unction t&at calls *see< *unction t&at calls *tell
'* 5 *open(Fmy-itmapG-mpH0 Fr-H$%
FIBI")AP '-itmap 5 FreeImage_LoadFrom.andle(FIF_B)P0 Iio0 (*i_&andle$*0 =$% *close(*$% i* (-itmap$ 1 ++ -itmap success*ully loaded4 9 FreeImage_!nload(-itmap$%
FreeImage-0ave
DLL_API BOOL DLL_CALLCONV FreeImage_#ave(F/ c&ar '*ilename0 int *lags FI_D FA!L"(=$$% _I)A( _FO/)A" *i*0 FIBI")AP 'di-0 const
This func"ion sa#es a pre#iously loaded FI%ITM(- "o a file! The firs" parame"er defines "he "ype of "he bi"map "o be sa#ed! For example, when FIF6%M- is passed, a %M- file is sa#ed )an o#er#iew of possible F@226IM(E26FO@M(T cons"an"s is a#ailable in Table $*! The second parame"er is "he name of "he bi"map "o be sa#ed! If "he file already exis"s i" is o#erwri""en! Do"e "ha" some bi"map sa#e plugins ha#e res"ric"ions on "he bi"map "ypes "hey can sa#e! For example, "he J-2E plugin can only sa#e +; bi" and < bi" greyscale bi"mapsA! 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! A In "he FreeImage J-2E plugin, < bi" palle"ised bi"maps are "ransparen"ly con#er"ed "o +; bi" when sa#ing!
(ppendi) =
++ 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 Fmy-itmapG-mpH0 =$$ 1 ++ -itmap success*ully saved4 9
Some bi"map sa#ers can recei#e parame"ers "o change "he sa#ing beha#iour! When "he parame"er is no" a#ailable or unused you can pass "he #alue , or NTB-26OF6%ITM(-O602F(7LT )e!g! %M-602F(7LT, I3O602F(7LT, e"c*! itmap type
%M2 @
Flag
%M-602F(7LT %M-6S(426@L2 2 @602F(7LT 2 @6FLO(T 2 @6DOD2 2 @6KI2 @6-IK 2 @6- @+; 2 @6%;; 2 @6L3
Description
Sa#e wi"hou" any compression 3ompress "he bi"map using @L2 when sa#ing Sa#e da"a as half wi"h piL:based wa#ele" compression Sa#e da"a as recommended* floa" ins"ead of as half )no"
Sa#e wi"h no compression Sa#e wi"h Llib compression, in blocks of $= scan lines Sa#e wi"h piL:based wa#ele" compression Sa#e wi"h lossy +;:bi" floa" compression Sa#e wi"h lossy ;;W floa" compression : goes "o ++W when combined wi"h 2 @6L3 Sa#e images wi"h one luminance and "wo chroma channels, ra"her "han as @E% )lossy compression* Sa#e wi"h a $=1$ ra"e Sa#e wi"h a 1$ ra"e Sa#e wi"h a $=1$ ra"e Sa#e wi"h a 1$ ra"e Sa#es wi"h good Cuali"y )TP1$* Sa#es wi"h superb Cuali"y )$,,1$* Sa#es wi"h good Cuali"y )TP1$* Sa#es wi"h normal Cuali"y )P,1$* Sa#es wi"h a#erage Cuali"y )+P1$* Sa#es wi"h bad Cuali"y )$,1$* Sa#e wi"h Cuali"y 1$ Sa#es as a progressi#e J-2E file )use R "o combine wi"h J-2E Cuali"y flags* Sa#e wi"h high ;x$ chroma subsampling );1$1$* Sa#e wi"h medium +x+ chroma subsampling );1+1,* : defaul" #alue Sa#e wi"h low +x$ chroma subsampling );1+1+* Sa#e wi"h no chroma subsampling );1;1;* On sa#ing, compu"e op"imal .uffman coding "ables )can reduce a few percen" of file siLe* Sa#e basic J-2E, wi"hou" me"ada"a or any markers )use R "o combine wi"h o"her J-2E flags* Sa#e wi"h KLib le#el = compression and no in"erlacing Sa#e using KLib le#el $ compression )defaul" #alue is =* Sa#e using KLib le#el recommended #alue* = compression )defaul"
J+I J-+ J-2E
J+I602F(7LT In"eger In"eger in U$!!P$+V in U$!!P$+V J-+602F(7LT J-2E602F(7LT J-2E6X7(LITBS7-2@% J-2E6X7(LITBEOO0 J-2E6X7(LITBDO@M(L J-2E6X7(LITB(42@(E2 J-2E6X7(LITB%(0 In"eger in U,!!$,,V
J-2E6-@OE@2SSI42 J-2E6S7%S(M-LIDE6;$$ J-2E6S7%S(M-LIDE6;+, J-2E6S7%S(M-LIDE6;++ J-2E6S7%S(M-LIDE6;;; J-2E6O-TIMIK2 J-2E6%(S2LID2 -DE -DE602F(7LT -DE6K6%2ST6S-220 -DE6K602F(7LT63OM-@2SSIOD -DE6K6%2ST63OM-@2SSIOD -DE6K6DO63OM-@2SSIOD
Sa#e using KLib le#el ? compression )defaul" #alue is =* Sa#e wi"hou" KLib compression
1# (ppendi)
itmap type
Flag
-DE6IDT2@L(320
Description
Sa#e using (damT in"erlacing )use R "o combine wi"h o"her sa#e flags* Sa#es "he bi"map as a binary file Sa#es "he bi"map as a binary file Sa#es "he bi"map as an (S3II file Sa#e using 33ITTF( ; compression for $:bi" bi"maps and LKW compression for any o"her bi"maps S"ores "ags for separa"ed 3MBI )use R "o combine wi"h TIFF compression flags* Sa#e using -(3I%ITS compression! Sa#e using 02FL(T2 compression )also known as KLI% compression* Sa#e using (0O%2 02FL(T2 compression Sa#e wi"hou" any compression Sa#e using 33ITT Eroup > fax encoding Sa#e using 33ITT Eroup ; fax encoding Sa#e using LKW compression Sa#e using J-2E compression )<:bi" greyscale and +;:bi" only! 0efaul" "o LKW for o"her bi"dep"hs*! Sa#e using LogLu# compression )only a#ailable wi"h @E%F images* Y defaul" "o LKW compression! Sa#es wi"hou" compression Sa#es wi"h @L2 compression
-%M, --M
-EM,
-DM602F(7LT -DM6S(426@(W -DM6S(426(S3II
TIFF
TIFF602F(7LT TIFF63MBI TIFF6-(3I%ITS TIFF602FL(T2 TIFF6(0O%2602FL(T2 TIFF6DOD2 TIFF633ITTF( > TIFF633ITTF( ; TIFF6LKW TIFF6J-2E TIFF6LOEL74
T(@E(
T(@E(602F(7LT T(@E(6S(426@L2
$able 5* /ptionnal encoder constants.
FreeImage-0ave9
DLL_API BOOL DLL_CALLCONV FreeImage_#ave!(F/ ;c&ar_t '*ilename0 int *lags FI_D FA!L"(=$$% _I)A( _FO/)A" *i*0 FIBI")AP 'di-0 const
This func"ion works exac"ly like FreeImage6Sa#e 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"ion does no"hing and re"urns F(LS2!
FreeImage-0ave$o<andle
DLL_API BOOL DLL_CALLCONV FreeImage_#ave"o.andle(F/ _I)A( _FO/)A" *i*0 FIBI")AP 'di-0 FreeImageIO 'io0 *i_&andle &andle0 int *lags FI_D FA!L"(=$$%
The FreeImageIO s"ruc"ure described earlier "o load a bi"map from an arbi"rary source can also be used "o sa#e bi"maps! Once again, FreeImage does no" implemen" "he way "he bi"map is sa#ed bu" le"s you implemen" "he desired func"ionali"y by popula"ing a FreeImageIO s"ruc"ure wi"h poin"ers "o func"ions! FreeImage will now call your func"ions "o wri"e, seek and "ell in a s"ream!
(ppendi) 11
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called J-itmapK FreeImageIO io% ioGread_proc 5 N!LL% ioG;rite_proc 5 7riteProc% ioGsee<_proc 5 #ee<Proc% ioGtell_proc 5 "ellProc% FIL ++ ++ ++ ++ usually pointer pointer pointer not needed *or saving to *unction t&at calls *;rite to *unction t&at calls *see< to *unction t&at calls *tell
'* 5 *open(Fmy-itmapG-mpH0 F;-H$%
i* (FreeImage_#ave"o.andle(FIF_B)P0 -itmap0 Iio0 (*i_&andle$*0 =$$ 1 ++ -itmap success*ully saved4 9 *close(*$%
FreeImage-Clone
DLL_API FIBI")AP ' DLL_CALLCONV FreeImage_Clone(FIBI")AP 'di-$%
Makes an exac" reproduc"ion of an exis"ing bi"map, including me"ada"a and a""ached profile if any!
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called Jdi-K FIBI")AP 'clone 5 FreeImage_Clone(di-$% i* (clone$ 1 ++ clone succeeded4 9 FreeImage_!nload(clone$%
FreeImage-9nload
DLL_API void DLL_CALLCONV FreeImage_!nload(FIBI")AP 'di-$%
0ele"es a pre#iously loaded FI%ITM(- from memory!
3ou always need to call this function once youDre done >ith a bitmap, or you >ill have a memory lea%!
1' (ppendi)
itmap information functions

Once a bi"map is loaded in"o memory, you can re"rie#e all kinds of informa"ion from i" or access 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( _"AP DLL_CALLCONV FreeImage_(etImage"ype(FIBI")AP 'di-$%
@e"urns "he da"a "ype of a bi"map )see Table +*!
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:siLe for palle"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" "his func"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 a member in %ITM(-IDFO.2(02@ named bi3lr7sed! The func"ion ac"ually re"urns "he con"en" of "his member!
FreeImage-.et 44
DLL_API unsigned DLL_CALLCONV FreeImage_(etBPP(FIBI")AP 'di-$%
@e"urns "he siLe of one pixel in "he bi"map in bi"s! For example when each pixel "akes >+:bi"s of space in "he bi"map, "his func"ion re"urns >+! -ossible bi" dep"hs are $, ;, <, $=, +;, >+ for s"andard bi"maps and $=:, >+:, ;<:, =;:, ?=: and $+<:bi" for non s"andard bi"maps!
FreeImage-.etEidth
DLL_API unsigned DLL_CALLCONV FreeImage_(et7idt&(FIBI")AP 'di-$%
@e"urns "he wid"h of "he bi"map in pixel uni"s!
FreeImage-.et<eight
DLL_API unsigned DLL_CALLCONV FreeImage_(et.eig&t(FIBI")AP 'di-$%
@e"urns "he heigh" of "he bi"map in pixel uni"s!
(ppendi) 13
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 in bytes! (s far as I know "he "erm Line is common "erminology for "he wid"h of a bi"map in 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 as pi"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 essential when using low le#el pixel manipula"ion func"ions )see also "he chap"er on -ixel access func"ions*!
FreeImage-.etDI 0i@e
DLL_API unsigned DLL_CALLCONV FreeImage_(etDIB#iLe(FIBI")AP 'di-$%
@e"urns "he siLe 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 real siLe of a FI%ITM(-, only "he siLe 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 "he pixel bi" dep"h is grea"er "han <*, "his func"ion re"urns D7LL!
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called Jdi-K i*(FreeImage_(etBPP(di-$ 55 B$ 1 ++ Build a greyscale palette /(BM!AD 'pal 5 FreeImage_(etPalette(di-$% *or (int i 5 =% i N ?ED% iOO$ 1 palPiQGrg-/ed 5 i% palPiQGrg-(reen 5 i% palPiQGrg-Blue 5 i% 9
15 (ppendi)
FreeImage-.etDots4er!eterF
DLL_API unsigned DLL_CALLCONV FreeImage_(etDotsPer)eterR(FIBI")AP 'di-$%
@e"urns "he horiLon"al resolu"ion, in pixels:per:me"er, of "he "arge" de#ice for "he bi"map!
FreeImage-.etDots4er!eter3
DLL_API unsigned DLL_CALLCONV FreeImage_(etDotsPer)eterA(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!eterF
DLL_API void DLL_CALLCONV FreeImage_#etDotsPer)eterR(FIBI")AP 'di-0 unsigned res$%
Se" "he horiLon"al resolu"ion, in pixels:per:me"er, of "he "arge" de#ice for "he bi"map!
FreeImage-0etDots4er!eter3
DLL_API void DLL_CALLCONV FreeImage_#etDotsPer)eterA(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<eader
$ ; < $= +; >+
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/_"AP 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
(ppendi) 15
Calue
FI36MIDIS%L(3I FI36MIDISW.IT2 FI36-(L2TT2 FI36@E% FI36@E%(L-.( FI363MBI
Description
Monochrome bi"map )$:bi"* 1 firs" pale""e en"ry is black! -alle"ised bi"map ); or <:bi"* and single channel non s"andard bi"map1 "he bi"map has a greyscale pale""e Monochrome bi"map )$:bi"* 1 firs" pale""e en"ry is whi"e! -alle"ised bi"map ); or <:bi"* 1 "he bi"map has an in#er"ed greyscale pale""e -ale""iLed bi"map )$, ; or < bi"* .igh:color bi"map )$=, +; or >+ bi"*, @E%$= or @E%F .igh:color bi"map wi"h an alpha channel )>+ bi" bi"map, @E%($= or @E%(F* 3MBI bi"map )>+ bi" only*
$able 5* F+,,-I!(.,-C/L/+-$34, constants. To be &udged greyscale )i!e! FI36MIDIS%L(3I*, 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 3MBI color model )i!e! FI363MBI* 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"e for "he pic"ure )single pixel, brigh"ness, con"ras"!!!*! Finally, "hey expor" an 3MBI separa"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 3MBI separa"ed images, because "he prin"er dri#ers will do "he con#ersion &ob! %u" in "he professional prin", "he proofed con#ersion is essen"ial "o ge" a brillian" prin" resul" )where no dri#er will do some"hing like con#ersion*! Tha"'s why prin"ed pic"ures in some magaLines look so much be""er "han our home:made prin"s!
FreeImage-.et+ed!as%
$ ; < $= +; >+
DLL_API unsigned DLL_CALLCONV FreeImage_(et/ed)as<(FIBI")AP 'di-$%
@e"urns a bi" pa""ern describing "he red color componen" of a pixel in a FI%ITM(-!
FreeImage-.et.reen!as%
$ ; < $= +; >+
DLL_API unsigned DLL_CALLCONV FreeImage_(et(reen)as<(FIBI")AP 'di-$%
@e"urns a bi" pa""ern describing "he green color componen" of a pixel in a FI%ITM(-!
FreeImage-.et lue!as%
$ ; < $= +; >+
DLL_API unsigned DLL_CALLCONV FreeImage_(etBlue)as<(FIBI")AP 'di-$%
@e"urns a bi" pa""ern describing "he blue color componen" of a pixel in a FI%ITM(-!
16 (ppendi)
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called Jdi-K unsigned red_mas<0 green_mas<0 -lue_mas<% red_mas< 5 FreeImage_(et/ed)as<(di-$% green_mas< 5 FreeImage_(et(reen)as<(di-$% -lue_mas< 5 FreeImage_(etBlue)as<(di-$% i*(FreeImage_(etBPP(di-$ 55 CD$ 1 i* ((red_mas< 55 FICD_EDE_/ D_)A#6$ II (green_mas< 55 FICD_EDE_(/ (-lue_mas< 55 FICD_EDE_BL! _)A#6$$ 1 ++ 7e are in /(BCD EDE mode 9 else 1 ++ 7e are in /(BCD EEE mode 9 9
N_)A#6$ II
FreeImage-.et$ransparencyCount
$ ; < $= +; >+
DLL_API unsigned DLL_CALLCONV FreeImage_(et"ransparencyCount(FIBI")AP 'di-$%
@e"urns "he number of "ransparen" colors in a palle"ised bi"map! When "he bi"map is no" palle"ised, FreeImage6Ee"Transparency3oun" always re"urns ,!
FreeImage-.et$ransparency$able
$ ; <
' DLL_CALLCONV FreeImage_(et"ransparency"a-le(FIBI")AP 'di-$% DLL_API BA"
@e"urns a poin"er "o "he bi"map's "ransparency "able! Only palle"ised bi"maps ha#e a "ransparency "able! .igh:color bi"maps s"ore "he "ransparency #alues direc"ly in "he bi"map bi"s! FreeImage6Ee"TransparencyTable re"urns D7LL for "hese bi"maps!
FreeImage-0et$ransparency$able
$ ; <
'ta-le0 DLL_API void DLL_CALLCONV FreeImage_#et"ransparency"a-le(FIBI")AP 'di-0 BA" int count$%
Se" "he bi"map's "ransparency "able! Only palle"ised bi"maps ha#e a "ransparency "able! .igh: color bi"maps s"ore "he "ransparency #alues direc"ly in "he bi"map bi"s! FreeImage6Se"TransparencyTable does no"hing for "hese bi"maps!
(ppendi) 1"
Sinclude 2FreeImageG&2 int main(int argc0 c&ar' argvPQ$ 1 FIBI")AP '&DIB?@-pp 5 FreeImage_Load(FIF_B)P0 2testG-mp20 =$% i* (&DIB?@-pp$ 1 ++ colorTUuantiLe ?@-pp (results in a B-pp -itmap to set transparency$ FIBI")AP '&DIBB-pp 5 FreeImage_ColorMuantiLe(&DIB?@-pp0 FIM_7!M!AN"$% ++ get palette and *ind -rig&t green /(BM!AD 'Palette 5 FreeImage_(etPalette(&DIBB-pp$% BA" "ransparencyP?EDQ% *or (unsigned i 5 =% i N ?ED% iOO$ 1 "ransparencyPiQ 5 =VFF% i* (PalettePiQGrg-(reen W5 =VF II PalettePiQGrg-Blue 55 =V== II PalettePiQGrg-/ed 55 =V==$ 1 "ransparencyPiQ 5 =V==% 9 9 ++ set t&e tranparency ta-le FreeImage_#et"ransparency"a-le(&DIBB-pp0 "ransparency0 ?ED$% ++ save B-pp image as transparent PN( FreeImage_#ave(FIF_PN(0 &DIBB-pp0 2testGpng20 =$% FreeImage_!nload(&DIB?@-pp$% FreeImage_!nload(&DIBB-pp$%
9 return =%
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" may accompany a bi"map! When calling "his func"ion wi"h a bi"map whose bi"dep"h is differen" from $:, ;:, <: or >+: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* or when "he inpu" dib con"ains alpha #alues )>+:bi" images, @E%($= or @E%(F images*! @e"urns F(LS2 o"herwise!
FreeImage-0et$ransparentInde)
$ ; <
DLL_API void DLL_CALLCONV FreeImage_#et"ransparentIndeV(FIBI")AP 'di-0 int indeV$%
Se"s "he index of "he pale""e en"ry "o be used as "ransparen" color for "he image specified! 0oes no"hing on high color images! This me"hod se"s "he index of "he pale""e en"ry "o be used as single "ransparen" color for "he image specified! This works on palle"ised images only and does no"hing for high color images! (l"hough i" is possible for palle"ised images "o ha#e more "han one "ransparen" color, "his me"hod se"s "he pale""e en"ry specified as "he single "ransparen" color for "he image! (ll o"her colors will be se" "o be non:"ransparen" by "his me"hod! (s wi"h FreeImage6Se"TransparencyTable, "his me"hod also se"s "he imageQs "ransparency proper"y "o T@72 )as i" is se" and ob"ained by FreeImage6Se"Transparen" and FreeImage6IsTransparen" respec"i#ely* for palle"ised images!
1& (ppendi)
FreeImage-.et$ransparentInde)
$ ; <
DLL_API int DLL_CALLCONV FreeImage_(et"ransparentIndeV(FIBI")AP 'di-$%
@e"urns "he pale""e en"ry used as "ransparen" color for "he image specified! Works for palle"ised images only and re"urns :$ for high color images or if "he image has no color se" "o be "ransparen"! (l"hough i" is possible for palle"ised images "o ha#e more "han one "ransparen" color, "his func"ion always re"urns "he index of "he firs" pale""e en"ry, se" "o be "ransparen"!
FreeImage-<as ac%groundColor
< +; >+
DLL_API BOOL DLL_CALLCONV FreeImage_.asBac<groundColor(FIBI")AP 'di-$%
@e"urns T@72 when "he image has a file background color, F(LS2 o"herwise!
FreeImage-.et ac%groundColor
< +; >+
DLL_API BOOL DLL_CALLCONV FreeImage_(etBac<groundColor(FIBI")AP 'di-0 /(BM!AD '-<color$%
@e"rie#es "he file background color of an image! @e"urns T@72 if successful, F(LS2 o"herwise! For <:bi" images, "he color index in "he pale""e is re"urned in "he rgb@eser#ed member of "he bkcolor parame"er!
FreeImage-0et ac%groundColor
< +; >+
DLL_API BOOL DLL_CALLCONV FreeImage_#etBac<groundColor(FIBI")AP 'di-0 /(BM!AD '-<color$%
Se" "he file background color of an image! When sa#ing an image "o -DE, "his background color is "ransparen"ly sa#ed "o "he -DE file! When "he bkcolor parame"er is D7LL, "he background color is remo#ed from "he image!
(ppendi) 1=
FreeImage-<as4i)els
DLL_API BOOL DLL_CALLCONV FreeImage_.asPiVels(FIBI")AP 'di-$%
@e"urns F(LS2 if "he bi"map does no" con"ain pixel da"a )i!e! if i" con"ains only header and possibly some me"ada"a*! .eader only bi"map can be loaded using "he FIF6LO(06DO-I 2LS load flag )see Table >*! This load flag will "ell "he decoder "o read header da"a and a#ailable me"ada"a and skip pixel da"a decoding! The memory siLe of "he dib is "hus reduced "o "he siLe of i"s members, excluding "he pixel buffer! @eading me"ada"a only informa"ion is fas" since no pixel decoding occurs! .eader only bi"map can be used wi"h %i"map informa"ion func"ions, Me"ada"a i"era"or! They canno" be used wi"h any pixel processing func"ion or by sa#ing func"ion! ( plugin can be asked for Fheader onlyG suppor" using FreeImage6FIFSuppor"sDo-ixels!
'# (ppendi)
BOOL test.eaderData(const c&ar 'lpsLPat&Name$ 1 int flags = FIF_LOAD_NOPIXELS; FIBI")AP 'di- 5 N!LL% try 1 ++ load a *ile using t&e FIF_LOAD_NOPIR L# *lag F/ _I)A( _FO/)A" *i* 5 FreeImage_(etFIFFromFilename(lpsLPat&Name$% assert(FreeImage_FIF#upportsNoPiVels(*i*$ 55 "/! $% di- 5 FreeImage_Load(*i*0 lpsLPat&Name0 *lags$% i*(4di-$ t&ro;(C$% ++ c&ec< t&at di- does not contains piVels BOOL -.asPiVel 5 FreeImage_.asPiVels(di-$% assert(-.asPiVel 55 FAL# $% ++ use accessors F/ _I)A( _"AP type 5 FreeImage_(etImage"ype(di-$% unsigned ;idt& 5 FreeImage_(et7idt&(di-$% unsigned &eig&t 5 FreeImage_(et.eig&t(di-$% unsigned -pp 5 FreeImage_(etBPP(di-$% ++ parse some metadata (see eGgG FreeImage_FindFirst)etadata$ Parse)etadata(di-0 FI)D_CO)) N"#$% Parse)etadata(di-0 FI)D_ RIF_)AIN$% Parse)etadata(di-0 FI)D_ RIF_ RIF$% Parse)etadata(di-0 FI)D_ RIF_(P#$% Parse)etadata(di-0 FI)D_ RIF_)A6 /NO" $% Parse)etadata(di-0 FI)D_IP"C$% Parse)etadata(di-0 FI)D_R)P$% ++ c&ec< *or a possi-le em-edded t&um-nail i*(FreeImage_(et"&um-nail(di-$$ 1 ++ t&um-nail is present FIBI")AP 't&um-nail 5 FreeImage_(et"&um-nail(di-$% 9 // you cannot access pixels BA" '-its 5 FreeImage_(etBits(di-$% assert(-its 55 N!LL$% FreeImage_!nload(di-$% return "/! % 9 catc&(int$ 1 i*(di-$ FreeImage_!nload(di-$% 9 9 return FAL# %
FreeImage-.et$humbnail
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_(et"&um-nail(FIBI")AP 'di-$%
Some image forma"s allow a "humbnail image "o be embedded "oge"her wi"h "he ou"pu" image file! When "his "humbnail image is presen" in a file, i" is au"oma"ically loaded by FreeImage )wha"e#er "he loading flag, e#en when using "he FIF6LO(06DO-I 2L flag*! Image forma"s "ha" curren"ly suppor" "humbnail loading are J-2E )2xif or JFIF forma"s*, -S0, 2 @, TE( and TIFF! FreeImage6Ee"Thumbnail re"rie#es a link "o "he "humbnail "ha" may be a#ailable wi"h a dib!
(ppendi) '1
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called J-itmapK i*( FreeImage_(et"&um-nail(-itmap$ $ 1 ++ a t&um-nail is availa-leX get a lin< to it FIBI")AP 't&um-nail 5 FreeImage_(et"&um-nail(-itmap$% unsigned ;idt& 5 FreeImage_(et7idt&(t&um-nail$% unsigned &eig&t 5 FreeImage_(et.eig&t(t&um-nail$% FIBI")AP 'clone 5 FreeImage_Clone(t&um-nail$% ++ GGG process YcloneY GGG FreeImage_!nload(clone$% ++ ne e! call F!eeI"age_#nloa$ on a t%u"&nail as its lifecycle is "anage$ inte!nally 9 ++ calling FreeImage_!nload on t&e -itmap ;ill destroy everyt&ing ++ (including its attac&ed t&um-nail$ FreeImage_!nload(-itmap$%
FreeImage-0et$humbnail
DLL_API BOOL DLL_CALLCONV FreeImage_#et"&um-nail(FIBI")AP 'di-0 FIBI")AP 't&um-nail$%
(""ach a "humbnail image "o a dib, so "ha" i" can be la"er s"ored "oge"her wi"h "he dib "o an oupu" image file forma"! If input parameter thumbnail is :9LL then the thumbnail is deleted from the dib. Image forma"s "ha" curren"ly suppor" "humbnail sa#ing are J-2E )JFIF forma"s*, 2 @, TE( and TIFF!
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called J-itmapK ++ create a t&um-nail and convert to a standard -itmap type FIBI")AP 't&um-nail 5 FreeImage_)a<e"&um-nail(-itmap0 C==0 "/! $% i*(t&um-nail$ 1 ++ attac& t&e t&um-nail to Y-itmapY FreeImage_#et"&um-nail(-itmap0 t&um-nail$% ++ t&um-nail is no longer needed FreeImage_!nload(t&um-nail$% 9 ++ save t&e -itmap as ZP (0 toget&er ;it& its em-edded t&um-nail FreeImage_#ave(FIF_ZP (0 -itmap0 2test_t&um-G[pg20 =$% ++ save t&e -itmap as ZP (0 ;it&out em-edded t&um-nail FreeImage_#et"&um-nail(-itmap0 N!LL$% FreeImage_#ave(FIF_ZP (0 -itmap0 2test_no_t&um-G[pg20 =$% ++ clear and eVit FreeImage_!nload(-itmap$%
Thumbnail images are almos" always s"andard bi"maps )e!g! images wi"h a FIT6%ITM(- image "ype*! The J-2E forma" suppor"s <: or +;:bi" "humbnails, while "he 2 @ forma" only suppor"s >+:bi" "humbnails! The TE( forma" needs a "humbnail wi"h "he same bi" dep"h as "he image! The TIF forma" has no res"ric"ion regarding "he "humbnail bi" dep"h, bu" a s"andard bi"map "ype is recommended!
'' (ppendi)
Filetype functions
The following func"ions re"rie#e "he F@226IM(E26FO@M(T from a bi"map by reading up "o $= by"es and analysing i"! Do"e "ha" for some bi"map "ypes no F@226IM(E26FO@M(T can be re"rie#ed! This has "o do wi"h "he bi":layou" of "he bi"map:"ypes, which are some"imes no" compa"ible wi"h FreeImage's file:"ype re"rie#al sys"em! The uniden"ifiable forma"s are1 37T, MDE, -30, T(@E( and W%M-! .owe#er, "hese forma"s can be iden"ified using "he FreeImage6Ee"FIFFromFilename func"ion!
FreeImage-.etFile$ype
DLL_API F/ _I)A( _FO/)A" DLL_CALLCONV FreeImage_(etFile"ype(const c&ar '*ilename0 int siLe FI_D FA!L"(=$$%
Orders FreeImage "o analyLe "he bi"map signa"ure! The func"ion "hen re"urns one of "he predefined F@226IM(E26FO@M(T cons"an"s or a bi"map iden"ifica"ion number regis"ered by a plugin! The si"e parame"er is curren"ly no" used and can be se" "o ,!
%ecause no" all forma"s can be iden"ified by "heir header )some images donQ" ha#e a header or one a" "he end of "he file*, FreeImage6Ee"FileType may re"urn FIF67DIDOWD whereas a plugin is a#ailable for "he file being analysed! In "his case, you can use FreeImage6Ee"FIFFromFilename "o guess "he file forma" from "he file ex"ension, bu" "his las" func"ion is slower and less accura"e!
+'' (eneric image loader ,param lpsLPat&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' lpsLPat&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(lpsLPat&Name0 =$% i*(*i* 55 FIF_!N6NO7N$ 1 ++ no signature \ ++ try to guess t&e *ile *ormat *rom t&e *ile eVtension *i* 5 FreeImage_(etFIFFromFilename(lpsLPat&Name$% 9 ++ c&ec< t&at t&e plugin &as reading capa-ilities GGG i*((*i* 45 FIF_!N6NO7N$ II FreeImage_FIF#upports/eading(*i*$$ 1 ++ o<0 letYs load t&e *ile FIBI")AP 'di- 5 FreeImage_Load(*i*0 lpsLPat&Name0 *lag$% ++ unless a -ad *ile *ormat0 ;e are done 4 return di-% 9 return N!LL% 9
FreeImage-.etFile$ype9
DLL_API F/ _I)A( _FO/)A" DLL_CALLCONV FreeImage_(etFile"ype!(const ;c&ar_t '*ilename0 int siLe FI_D FA!L"(=$$%
This func"ion works exac"ly like FreeImage6Ee"FileType 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"ion does no"hing and re"urns FIF67DIDOWD!
(ppendi) '3
FreeImage-.etFile$ypeFrom<andle
DLL_API F/ _I)A( _FO/)A" DLL_CALLCONV FreeImage_(etFile"ypeFrom.andle(FreeImageIO 'io0 *i_&andle &andle0 int siLe FI_D FA!L"(=$$%
7ses "he FreeImageIO s"ruc"ure as described in "he "opic %i"map managemen" func"ions "o iden"ify a bi"map "ype! Dow "he bi"map bi"s are re"rie#ed from an arbi"rary place!
FreeImage-.etFile$ypeFrom!emory
DLL_API F/ _I)A( _FO/)A" DLL_CALLCONV FreeImage_(etFile"ypeFrom)emory(FI) )O/A 'stream0 int siLe FI_D FA!L"(=$$%
7ses a memory handle "o iden"ify a bi"map "ype! The bi"map bi"s are re"rie#ed from an arbi"rary place )see "he chap"er on Memory I8O s"reams for more informa"ion on memory handles*!
'5 (ppendi)
4i)el access functions

The pixel access func"ions pro#ide you wi"h an easy way "o read, wri"e and work pixel:by:pixel wi"h FI%ITM(- da"a! FreeImage is able "o work no" only wi"h s"andard bi"map da"a )e!g! $:, ;:, <:, $=:, +;: and >+: bi"* bu" also wi"h scien"ific da"a such as $=:bi" greyscale images, or images made up of long, double or complex #alues )of"en used in signal and image processing algori"hms*! (n o#er#iew of "he suppor"ed da"a "ypes is gi#en in Table +!
In FreeImage, FI%ITM(- are based on a coordina"e sys"em "ha" is upside down rela"i#e "o usual graphics con#en"ions! Thus, "he scanlines are stored upside do>n, wi"h "he firs" scan in memory being "he bo""ommos" scan in "he image!
it Formats In a FI%ITM(- "he forma" of "he bi"s are defined by a pixel's bi" dep"h "ha" can be read #ia a call "o FreeImage6Ee"%-- )see also FreeImage6Ee"ImageType*! -ossible bi" dep"hs include $:, ;:, <:, $=:, +;:, >+:, ;<:, =;:, ?=: and $+<:bi"! (ll forma"s share "he following rules1 2#ery scanline is 0WO@0:aligned! The scanline is buffered "o alignmen"M "he buffering is se" "o ,! The scanlines are s"ored upside down, wi"h "he firs" scan )scan ,* in memory being "he bo""ommos" scan in "he image! $:bi" 0I%s are s"ored using each bi" as an index in"o "he color "able! The mos" significan" bi" is "he lef"mos" pixel! ;:bi" 0I%s are s"ored wi"h each ; bi"s represen"ing an index in"o "he color "able! The mos" significan" nibble is "he lef"mos" pixel! <:bi" 0I%s are "he easies" "o s"ore because each by"e is an index in"o "he color "able! +;:bi" 0I%s ha#e e#ery > by"es represen"ing a color, using "he same ordering as "he @E%T@I-L2 s"ruc"ure! >+: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%! 3omplex image "ypes are s"ored in a similar way as +;: or >+bi" 0I%, using "he same ordering as "he FI3OM-L2 s"ruc"ure! $=:bi" @E%U(V or floa" @E%U(V image "ypes are s"ored in a similar way as +;: or >+bi" 0I%, using "he same ordering as "he FI@E%U(V$= or FI@E%U(VF s"ruc"ures!
2ach forma" has "he following specifics1
Color model ( color model is an abs"rac" ma"hema"ical model describing "he way colors can be represen"ed as "uples of numbers, "ypically as "hree or four #alues or color componen"s )e!g! @E% and 3MBI are color models*! FreeImage mainly uses "he @E%U(V color model "o represen" 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""le 2ndian processor )Windows, Linux* and uses a @E%U(V pixel layou" under a %ig 2ndian
(ppendi) '5
processor )Mac OS or any %ig 2ndian Linux 8 7nix*! This choice was made "o ease "he use of FreeImage wi"h graphics (-I! This sub"le difference is howe#er "ransparen" "o "he user! In order "o make pixel access OS independen", FreeImage defines a se" of macros used "o se" or ge" indi#idual color componen"s in a +;: or >+:bi" 0I%! Channel
@ed Ereen %lue (lpha
4i)el position
FI6@E%(6@20 FI6@E%(6E@22D FI6@E%(6%L72 FI6@E%(6(L-.(
(ssociated mas%
FI6@E%(6@206M(SI FI6@E%(6E@22D6M(SI FI6@E%(6%L726M(SI FI6@E%(6(L-.(6M(SI
$able 6* 4i)el access macros and associated mas%s for '57 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 "o wri"e OS independen" code!
The following sample shows how "o use "hese macros when working wi"h a >+:bi" dib1
++ Allocate a >?T-it diFIBI")AP 'di- 5 FreeImage_Allocate(EC?0 EC?0 >?0 FI_/(BA_/ D_)A#60 FI_/(BA_(/ N_)A#60 FI_/(BA_BL! _)A#6$% ++ Calculate t&e num-er o* -ytes per piVel (> *or ?@T-it or @ *or >?T-it$ int -ytespp 5 FreeImage_(etLine(di-$ + FreeImage_(et7idt&(di-$% *or(unsigned y 5 =% y N FreeImage_(et.eig&t(di-$% yOO$ 1 BA" '-its 5 FreeImage_(et#canLine(di-0 y$% *or(unsigned V 5 =% V N ++ #et piVel color to -itsPFI_/(BA_/ DQ 5 -itsPFI_/(BA_(/ NQ 5 -itsPFI_/(BA_BL! Q 5 -itsPFI_/(BA_ALP.AQ 5 ++ [ump to neVt piVel -its O5 -ytespp% FreeImage_(et7idt&(di-$% VOO$ 1 green ;it& a transparency o* C?B =% ?EE% =% C?B%
FreeImage-.et its
DLL_API BA" '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"es correc"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 on a $= 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)
++ 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( _"AP image_type 5 FreeImage_(etImage"ype(di-$%
++ test piVel access avoiding scanline calculations ++ to speedTup t&e image processing i*(image_type 55 FI"_/(BF$ 1 BA" '-its 5 (BA" '$FreeImage_(etBits(di-$% *or(y 5 =% y N &eig&t% yOO$ 1 FI/(BF 'piVel 5 (FI/(BF'$-its% *or(V 5 =% V N ;idt&% VOO$ 1 piVelPVQGred 5 C?B% piVelPVQGgreen 5 C?B% piVelPVQG-lue 5 C?B% 9 ++ neVt line -its O5 pitc&% 9 9 else i*((image_type 55 FI"_BI")AP$ II (FreeImage_(etBPP(di-$ 55 ?@$$ 1 BA" '-its 5 (BA" '$FreeImage_(etBits(di-$% *or(y 5 =% y N &eig&t% yOO$ 1 BA" 'piVel 5 (BA" '$-its% *or(V 5 =% V N ;idt&% VOO$ 1 piVelPFI_/(BA_/ DQ 5 C?B% piVelPFI_/(BA_(/ NQ 5 C?B% piVelPFI_/(BA_BL! Q 5 C?B% piVel O5 >% 9 ++ neVt line -its O5 pitc&% 9 9
FreeImage-.et0canLine
DLL_API BA" '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 of FreeImage6Ee"%-- and FreeImage6Ee"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 siLe 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!
(ppendi) '"
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called JimageK unsigned V0 y% F/ _I)A( _"AP image_type 5 FreeImage_(etImage"ype(image$%
++ test piVel access s;itc&(image_type$ 1 case FI"_BI")APX i*(FreeImage_(etBPP(image$ 55 B$ 1 *or(y 5 =% y N FreeImage_(et.eig&t(image$% yOO$ 1 BA" '-its 5 (BA" '$FreeImage_(et#canLine(image0 y$% *or(V 5 =% V N FreeImage_(et7idt&(image$% VOO$ 1 -itsPVQ 5 C?B% 9 9 9 -rea<% case FI"_!IN"CDX *or(y 5 =% y N FreeImage_(et.eig&t(image$% yOO$ 1 unsigned s&ort '-its 5 (unsigned s&ort '$FreeImage_(et#canLine(image0 y$% *or(V 5 =% V N FreeImage_(et7idt&(image$% VOO$ 1 -itsPVQ 5 C?B% 9 9 -rea<% case FI"_IN"CDX *or(y 5 =% y N FreeImage_(et.eig&t(image$% yOO$ 1 s&ort '-its 5 (s&ort '$FreeImage_(et#canLine(image0 y$% *or(V 5 =% V N FreeImage_(et7idt&(image$% VOO$ 1 -itsPVQ 5 C?B% 9 9 -rea<% case FI"_!IN">?X *or(y 5 =% y N FreeImage_(et.eig&t(image$% yOO$ 1 D7O/D '-its 5 (D7O/D '$FreeImage_(et#canLine(image0 y$% *or(V 5 =% V N FreeImage_(et7idt&(image$% VOO$ 1 -itsPVQ 5 C?B% 9 9 -rea<% case FI"_IN">?X *or(y 5 =% y N FreeImage_(et.eig&t(image$% yOO$ 1 LON( '-its 5 (LON( '$FreeImage_(et#canLine(image0 y$% *or(V 5 =% V N FreeImage_(et7idt&(image$% VOO$ 1 -itsPVQ 5 C?B% 9 9 -rea<% case FI"_FLOA"X *or(y 5 =% y N FreeImage_(et.eig&t(image$% yOO$ 1 *loat '-its 5 (*loat '$FreeImage_(et#canLine(image0 y$% *or(V 5 =% V N FreeImage_(et7idt&(image$% VOO$ 1 -itsPVQ 5 C?B% 9 9 -rea<% case FI"_DO!BL X *or(y 5 =% y N FreeImage_(et.eig&t(image$% yOO$ 1 dou-le '-its 5 (dou-le '$FreeImage_(et#canLine(image0 y$% *or(V 5 =% V N FreeImage_(et7idt&(image$% VOO$ 1 -itsPVQ 5 C?B% 9 9 -rea<% case FI"_CO)PL RX *or(y 5 =% y N FreeImage_(et.eig&t(image$% yOO$ 1 FICO)PL R '-its 5 (FICO)PL R '$FreeImage_(et#canLine(image0 y$% *or(V 5 =% V N FreeImage_(et7idt&(image$% VOO$ 1 -itsPVQGr 5 C?B% -itsPVQGi 5 C?B% 9 9 -rea<% case FI"_/(BCDX *or(y 5 =% y N FreeImage_(et.eig&t(image$% yOO$ 1 FI/(BCD '-its 5 (FI/(BCD '$FreeImage_(et#canLine(image0 y$% *or(V 5 =% V N FreeImage_(et7idt&(image$% VOO$ 1 -itsPVQGred 5 C?B%
'& (ppendi)
9 9 -rea<% case FI"_/(BFX *or(y 5 =% y N FreeImage_(et.eig&t(image$% yOO$ 1 FI/(BF '-its 5 (FI/(BF '$FreeImage_(et#canLine(image0 y$% *or(V 5 =% V N FreeImage_(et7idt&(image$% VOO$ 1 -itsPVQGred 5 C?B% -itsPVQGgreen 5 C?B% -itsPVQG-lue 5 C?B% 9 9 -rea<% case FI"_/(BACDX *or(y 5 =% y N FreeImage_(et.eig&t(image$% yOO$ 1 FI/(BACD '-its 5 (FI/(BACD '$FreeImage_(et#canLine(image0 y$% *or(V 5 =% V N FreeImage_(et7idt&(image$% VOO$ 1 -itsPVQGred 5 C?B% -itsPVQGgreen 5 C?B% -itsPVQG-lue 5 C?B% -itsPVQGalp&a 5 C?B% 9 9 -rea<% case FI"_/(BAFX *or(y 5 =% y N FreeImage_(et.eig&t(image$% yOO$ 1 FI/(BAF '-its 5 (FI/(BAF '$FreeImage_(et#canLine(image0 y$% *or(V 5 =% V N FreeImage_(et7idt&(image$% VOO$ 1 -itsPVQGred 5 C?B% -itsPVQGgreen 5 C?B% -itsPVQG-lue 5 C?B% -itsPVQGalp&a 5 C?B% 9 9 -rea<%
-itsPVQGgreen 5 C?B% -itsPVQG-lue 5 C?B%
FreeImage-.et4i)elInde)
$ ; <
DLL_API BOOL DLL_CALLCONV FreeImage_(etPiVelIndeV(FIBI")AP 'di-0 unsigned V0 unsigned y0 BA" 'value$%
Ee" "he pixel index of a pale""iLed image a" posi"ion )x, y*, including range check )slow access*! -arame"er x is "he pixel posi"ion in horiLon"al direc"ion, and parame"er y is "he pixel posi"ion in #er"ical direc"ion! The func"ion re"urns T@72 on success, and re"urns F(LS2 o"herwise )e!g! for @E%U(V images*!
FreeImage-.et4i)elColor
$= +; >+
DLL_API BOOL DLL_CALLCONV FreeImage_(etPiVelColor(FIBI")AP 'di-0 unsigned V0 unsigned y0 /(BM!AD 'value$%
Ee" "he pixel color of a $=:, +;: or >+:bi" image a" posi"ion )x, y*, including range check )slow access*! -arame"er x is "he pixel posi"ion in horiLon"al direc"ion, and parame"er y is "he pixel posi"ion in #er"ical direc"ion! The func"ion re"urns T@72 on success, and re"urns F(LS2 o"herwise )e!g! for pale""iLed images*!
FreeImage-0et4i)elInde)
$ ; <
DLL_API BOOL DLL_CALLCONV FreeImage_#etPiVelIndeV(FIBI")AP 'di-0 unsigned V0 unsigned y0 BA" 'value$%
(ppendi) '=
Se" "he pixel index of a pale""iLed image a" posi"ion )x, y*, including range check )slow access*! -arame"er x is "he pixel posi"ion in horiLon"al direc"ion, and parame"er y is "he pixel posi"ion in #er"ical direc"ion! The func"ion re"urns T@72 on success, and re"urns F(LS2 o"herwise )e!g! for @E%U(V images*!
FreeImage-0et4i)elColor
$= +; >+
DLL_API BOOL DLL_CALLCONV FreeImage_#etPiVelColor(FIBI")AP 'di-0 unsigned V0 unsigned y0 /(BM!AD 'value$%
Se" "he pixel color of a $=:, +;: or >+:bi" image a" posi"ion )x, y*, including range check )slow access*! -arame"er x is "he pixel posi"ion in horiLon"al direc"ion, and parame"er y is "he pixel posi"ion in #er"ical direc"ion! The func"ion re"urns T@72 on success, and re"urns F(LS2 o"herwise )e!g! for pale""iLed images*!
3# (ppendi)
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 in memory 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"y considera"ions are "ransparen"ly handled by "he con#ersion func"ions, so "ha" you can la"er sa#e con#er"ed bi"maps in an OS independen" manner!
FreeImage-Convert$o5 its
$ ; < $= +; >+
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" was a monochrome or greyscale bi"map )$ or <:bi"*, "he end resul" will be a greyscale bi"map, o"herwise )$:bi" palle"ised bi"maps* i" will be a palle"ised bi"map! ( clone of "he inpu" bi"map is re"urned for ;:bi" bi"maps! D%1 here FgreyscaleG means "ha" "he resul"ing bi"map will ha#e grey colors, bu" "he pale""e won'" be a linear greyscale pale""e! Thus, FreeImage6Ee"3olorType will re"urn FI36-(L2TT2!
FreeImage-Convert$o& its
$ ; < $= +; >+ $=7IDT$=
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"oBBits(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" was a monochrome or greyscale bi"map )$ or ;:bi"*, "he end resul" will be a greyscale bi"map, o"herwise )$ or ;:bi" palle"ised bi"maps* i" will be a palle"ised bi"map! ( clone of "he inpu" bi"map is re"urned for <:bi" bi"maps! When crea"ing "he greyscale pale""e, "he greyscale in"ensi"y of a resul" pixel is based on red, green, and blue le#els of "he corresponding source pixel using "he following formula )known as @ec! T,? formula*1 grey S ),!+$+= x @ 9 ,!T$P+ A E 9 ,!,T++ x %* The #alues ,!+$+=, ,!T$P+ and ,!,T++ represen" "he rela"i#e red, green, and blue in"ensi"ies! For $=:bi" greyscale images )images whose "ype is FIT67IDT$=*, con#ersion is done by di#iding "he $=:bi" channel by +P= )see also FreeImage63on#er"ToS"andardType*! ( D7LL #alue is re"urned for o"her non:s"andard bi"map "ypes!
FreeImage-Convert$o.reyscale
$ ; < $= +; >+ $=7IDT$=
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"o(reyscale(FIBI")AP 'di-$%
3on#er"s a bi"map "o a <:bi" greyscale image wi"h a linear ramp! 3on"rary "o "he FreeImage63on#er"To<%i"s func"ion, $:, ;: and <:bi" palle"ised images are correc"ly con#er"ed, as well as images wi"h a FI36MIDISW.IT2 color "ype!
(ppendi) 31
FreeImage-Convert$o16 its555
$ ; < $= +; >+
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"oCDBitsEEE(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 green and 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$o16 its565
$ ; < $= +; >+
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"oCDBitsEDE(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 green and P bi"s blue! ( clone of "he inpu" bi"map is re"urned for $=:bi" P=P bi"maps
FreeImage-Convert$o'5 its
$ ; < $= +; >+ ;<@E%$=
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"o?@Bits(FIBI")AP 'di-$%
3on#er"s a bi"map "o +; bi"s! ( clone of "he inpu" bi"map is re"urned for +;:bi" bi"maps! For ;<:bi" @E% images, con#ersion is done by di#iding each $=:bi" channel by +P=! ( D7LL #alue is re"urned for o"her non:s"andard bi"map "ypes!
FreeImage-Convert$o3' its
$ ; < $= +; >+ ;<@E%$= =;@E%($=
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"o>?Bits(FIBI")AP 'di-$%
3on#er"s a bi"map "o >+ bi"s! ( clone of "he inpu" bi"map is re"urned for >+:bi" bi"maps! For ;<:bi" @E% images, con#ersion is done by di#iding each $=:bi" channel by +P= and by se""ing "he alpha channel "o an opaCue #alue ),xFF*! For =;:bi" @E%( images, con#ersion is done by di#iding each $=:bi" channel by +P=! ( D7LL #alue is re"urned for o"her non:s"andard bi"map "ypes!
FreeImage-Color8uanti@e
+;
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_ColorMuantiLe(FIBI")AP 'di-0 F/ _I)A( _M!AN"I] UuantiLe$%
Xuan"iLes a high:color +;:bi" bi"map "o an <:bi" pale""e color bi"map! The Cuan"iLe parame"er specifies "he color reduc"ion algori"hm "o be used1 4arameter
FIX6W7X7(DT FIX6DDX7(DT
8uanti@ation method
iaolin Wu color Cuan"iLa"ion algori"hm DeuXuan" neural:ne" Cuan"iLa"ion algori"hm by (n"hony 0ekker
$able "* F+,,-I!(.,-89(:$I;, constants. +eferences
3' (ppendi)
Wu, iaolin, 2fficien" S"a"is"ical 3ompu"a"ions for Op"imal 3olor Xuan"iLa"ion! In Eraphics Eems, #ol! II, p! $+=:$>>! UOnlineV h""p188www!ece!mcmas"er!ca8Zxwu8 0ekker (! .!, Iohonen neural ne"works for op"imal color Cuan"iLa"ion! De"work1 3ompu"a"ion in Deural Sys"ems, 4olume P, Dumber >, Ins"i"u"e of -hysics -ublishing, $??;! UOnlineV h""p188members!oLemail!com!au8Zdekker8D27X7(DT!.TML
FreeImage-Color8uanti@e,)
+;
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_ColorMuantiLe V(FIBI")AP 'di-0 F/ _I)A( _M!AN"I] UuantiLe FI_D FA!L"(FIM_7!M!AN"$0 int Palette#iLe FI_D FA!L"(?ED$0 int /eserve#iLe FI_D FA!L"(=$0 /(BM!AD '/eservePalette FI_D FA!L"(N!LL$$%
FreeImage63olorXuan"iLe2x is an ex"ension "o "he FreeImage63olorXuan"iLe func"ion "ha" pro#ides addi"ional op"ions used "o Cuan"iLe a +;:bi" image "o any number of colors )up "o +P=*, as well as Cuan"iLe a +;:bi" image using a par"ial or full pro#ided pale""e! The #alette$i"e parame"er is "he siLe of "he desired ou"pu" pale""e! %eser&e$i"e is "he siLe of "he pro#ided pale""e, gi#en by "he %eser&e#alette inpu" 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-_paletteP?CDQ% ++ list o* t&e ?CD 2;e-Tsa*e2 colors (/(B increments o* EC$ ++ GGG ++ ++ ++ ++ ++ ++ ++ ++ ++ Per*orm a color UuantiLation using a user supplied palette "&e goal o* FreeImage_ColorMuantiLe V ;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* siLe ?EE to UuantiLe t&e imageG "&e output palette ;ill contain a miV o* t&e ?CD and >^ colors0 -ut not in any particular orderG Palette entry ?EE (t&e ?EDt& 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<ing valid piVel data -ecome transparentG
FIBI")AP 'di-B_a 5 FreeImage_ColorMuantiLe V(di-0 FIM_NNM!AN"0 ?EE0 ?CD0 ;e-_palette$% ++ Ot&er uses o* t&e *unction ++ Only use ?EE colors0 so t&e ?EDt& can -e used *or transparency FIBI")AP 'di-B_- 5 FreeImage_ColorMuantiLe V(di-0 FIM_NNM!AN"0 ?EE0 =0 N!LL$% ++ (enerate no additional colors0 only use t&e ;e-Tsa*e colors FIBI")AP 'di-B_c 5 FreeImage_ColorMuantiLe V(di-0 FIM_NNM!AN"0 ?CD0 ?CD0 ;e-_palette$% ++ MuantiLe using a palette *rom a di**erent di/(BM!AD anot&er_paletteP?EDQ% ++ GGG FIBI")AP 'di-B_d 5 FreeImage_ColorMuantiLe V(di-0 FIM_NNM!AN"0 ?ED0 ?ED0 anot&er_palette$% ++ GGG FreeImage_!nload(di-B_a$% FreeImage_!nload(di-B_-$% FreeImage_!nload(di-B_c$% FreeImage_!nload(di-B_d$%
When using FreeImage63olorXuan"iLe2x, "he #alette$i"e se""ing works on bo"h DD and Wu Cuan"iLers, wi"h any #alue +:+P=, bu" "he %eser&e$i"e8%eser&e#alette se""ings work on "he DD Cuan"iLer only!
(ppendi) 33
FreeImage-$hreshold
$ ; < $= +; >+
"$% DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_"&res&old(FIBI")AP 'di-0 BA"
3on#er"s a bi"map "o $:bi" monochrome bi"map using a "hreshold T be"ween U,!!+PPV! The func"ion firs" con#er"s "he bi"map "o a <:bi" greyscale bi"map! Then, any brigh"ness le#el "ha" is less "han T is se" "o Lero, o"herwise "o $! For $:bi" inpu" bi"maps, "he func"ion clones "he inpu" bi"map and builds a monochrome pale""e!
FreeImage-Dither
$ ; < $= +; >+
_I)A( _DI". / DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Dit&er(FIBI")AP 'di-0 F/ 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 <:bi" greyscale bi"map! Then, "he bi"map is di"hered using one of "he following algori"hms1 4arameter
FI06FS FI06%(B2@;x; FI06%(B2@<x< FI06%(B2@$=x$= FI063L7ST2@=x= FI063L7ST2@<x< FI063L7ST2@$=x$=
Dithering method
Floyd [ S"einberg error diffusion algori"hm %ayer ordered dispersed do" di"hering )order + Y ;x; :di"hering ma"rix* %ayer ordered dispersed do" di"hering )order > Y <x< :di"hering ma"rix* %ayer ordered dispersed do" di"hering )order ; Y $=x$= di"hering ma"rix* Ordered clus"ered do" di"hering )order > : =x= ma"rix* Ordered clus"ered do" di"hering )order ; : <x< ma"rix* Ordered clus"ered do" di"hering )order < : $=x$= ma"rix*
$able &* F+,,-I!(.,-DI$<,+ constants. +eferences 7lichney, @!, 0igi"al .alf"oning! The MIT -ress, 3ambridge, M(, $?<T! .awley S!, Ordered 0i"hering! Eraphics Eems, (cademic -ress, $??,!
FreeImage-ConvertFrom+a> its
$ ; < $= +; >+
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_ConvertFrom/a;Bits(BA" '-its0 int ;idt&0 int &eig&t0 int pitc&0 unsigned -pp0 unsigned red_mas<0 unsigned green_mas<0 unsigned -lue_mas<0 BOOL topdo;n FI_D FA!L"(FAL# $$%
3on#er"s a raw bi"map somewhere in memory "o a FI%ITM(-! The parame"ers in "his func"ion are used "o describe "he raw bi"map! The firs" parame"er is a poin"er "o "he s"ar" of "he raw bi"s! The wid"h and heigh" parame"er describe "he siLe of "he bi"map! The pi"ch defines "he "o"al wid"h of a scanline in "he source bi"map, including padding by"es "ha" may be applied! The bpp parame"er "ells FreeImage wha" "he bi" dep"h of "he bi"map is! The red6mask, green6mask and blue6mask parame"ers "ell FreeImage "he bi":layou" of "he color componen"s in "he bi"map! The las" parame"er, "opdown, will s"ore "he bi"map "op:lef" pixel firs" when i" is T@72 or bo""om:lef" pixel firs" when i" is F(LS2!
35 (ppendi)
When "he source bi"map uses a >+:bi" padding, you can calcula"e "he pi"ch using "he following formula1 in" pi"ch S ))))bpp A wid"h* 9 >$* 8 >+* A ;*M
FreeImage-Convert$o+a> its
$ ; < $= +; >+
DLL_API void DLL_CALLCONV FreeImage_Convert"o/a;Bits(BA" '-its0 FIBI")AP 'di-0 int pitc&0 unsigned -pp0 unsigned red_mas<0 unsigned green_mas<0 unsigned -lue_mas<0 BOOL topdo;n FI_D FA!L"(FAL# $$%
3on#er"s a FI%ITM(- "o a raw piece of memory! The layou" of "he memory is described in "he passed parame"ers, which are "he same as in "he pre#ious func"ion! The las" parame"er, topdo n, will s"ore "he bi"map "op:lef" pixel firs" when i" is T@72 or bo""om:lef" pixel firs" when i" is F(LS2!
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called Jdi-K ++ convert a -itmap to a >?T-it ra; -u**er (topTle*t piVel *irst$ ++ TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT FIBI")AP 'src 5 FreeImage_Convert"o>?Bits(di-$% FreeImage_!nload(di-$% ++ Allocate a ra; -u**er int ;idt& 5 FreeImage_(et7idt&(src$% int &eig&t 5 FreeImage_(et.eig&t(src$% int scan_;idt& 5 FreeImage_(etPitc&(src$% BA" '-its 5 (BA" '$malloc(&eig&t ' scan_;idt&$% ++ convert t&e -itmap to ra; -its (topTle*t piVel *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 piVel *irst$ to a FIBI")AP ++ TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT FIBI")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 BOOL scale_linear FI_D FA!L"("/! $$%
3on#er"s a non s"andard image whose color "ype is FI36MIDIS%L(3I "o a s"andard <:bi" greyscale image )see Table ? for allowed con#ersions*! When "he scale_linear parame"er is T@72, con#ersion is done by scaling linearly each pixel #alue from Umin, maxV "o an in"eger #alue be"ween U,!!+PPV, where min and max are "he minimum and maximum pixel #alues in "he image! When scale_linear is F(LS2, con#ersion is done by rounding each pixel #alue "o an in"eger be"ween U,!!+PPV! @ounding is done using "he following formula1 ds"6pixel S )%BT2* MID)+PP, M( ),, C** where in" C S in")src6pixel 9 ,!P*M The func"ion re"urns "he con#er"ed <:bi" greyscale image! For s"andard images, a clone of "he inpu" image is re"urned! For complex images, "he magni"ude is ex"rac"ed as a double image and "hen con#er"ed according "o "he scale parame"er!
(ppendi) 35
FreeImage-Convert$o$ype
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"o"ype(FIBI")AP 'src0 F/ dst_type0 BOOL scale_linear FI_D FA!L"("/! $$% _I)A( _"AP
3on#er"s an image of any "ype "o "ype dst_type! When dst_type is eCual "o FIT6%ITM(-, "he func"ion calls FreeImage63on#er"ToS"andardType! O"herwise, con#ersion is done using s"andard 3 language cas"ing con#en"ion! When a con#ersion is no" allowed, a D7LL #alue is re"urned and an error message is "hrown )i" can be ca"ched using FreeImage6Se"Ou"pu"Message*! The following con#ersions are curren"ly allowed by "he library )o"her con#ersions may be added easily if needed*1
FIT63OM-L2
FIT60O7%L2
FIT6@E%($=
FIT6%ITM(-
FIT6IDT$=
FIT6IDT>+
FIT6%ITM(FIT67IDT$= FIT6IDT$= FIT67IDT>+ FIT6IDT>+ FIT6FLO(T FIT60O7%L2 FIT63OM-L2 FIT6@E%$= FIT6@E%($= FIT6@E%F FIT6@E%(F
FIT6@E%(F
FIT67IDT$=
FIT67IDT>+
FIT6@E%$=
FIT6FLO(T
FIT6@E%F
color legend re"urns FreeImage63lone re"urns FreeImage63on#er"To+;%i"s re"urns FreeImage63on#er"To>+%i"s re"urns FreeImage63on#er"To7IDT$= re"urns FreeImage63on#er"To@E%$= re"urns FreeImage63on#er"ToFloa" re"urns FreeImage63on#er"To@E%F re"urns FreeImage63on#er"ToS"andardType con#ersion is done using s"andard 3 language cas"ing con#en"ion
$able =* itmap type conversions allo>ed by FreeImage.
FreeImage-Convert$oFloat
$ ; < $= +; >+ $=7IDT$= ;<@E%$= =;@E%($= >+FLO(T ?=@E%F $+<@E%(F
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"oFloat(FIBI")AP 'di-$%
3on#er"s an image "o a FIT6FLO(T image "ype! 3on#ersion is done as follows1 FIT6%ITM(- "ype1 "he inpu" dib is firs" con#er"ed "o a <:bi" greyscale image using FreeImage63on#er"ToEreyscale, "hen each pixel #alue is di#ided by +PP so "ha" "he ou"pu" image is in "he range U,!!$V! FIT67IDT$= "ype1 con#ersion is done by copying "he source in"eger pixel #alues in"o "he des"ina"ion floa" pixel #alues, "hen each pixel #alue is di#ided by =PP>P so "ha" "he ou"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, "hen each 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 "he con#ersion func"ion! FIT6@E%U(VF "ype1 "he inpu" dib is con#er"ed "o a >+:bi" floa" image! When an alpha channel 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)
When crea"ing "he greyscale floa" image, "he luminance L )or greyscale in"ensi"y* of a resul" pixel is calcula"ed from "he s@E% model using a 0=P whi"e poin", using "he @ec!T,? formula 1 L S ) ,!+$+= A r * 9 ) ,!T$P+ A g * 9 ) ,!,T++ A b * The #alues ,!+$+=, ,!T$P+ and ,!,T++ represen" "he rela"i#e red, green, and blue in"ensi"ies!
FreeImage-Convert$o+. F
$ ; < $= +; >+ $=7IDT$= ;<@E%$= =;@E%($= >+FLO(T ?=@E%F $+<@E%(F
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"o/(BF(FIBI")AP 'di-$%
3on#er"s a +;: or >+:bi" @E%)(* s"andard image or a ;<: or ?=:bi" @E%)(* image "o a FIT6@E%F "ype image! 3on#ersion is done by copying "he source in"eger pixel #alues in"o "he des"ina"ion floa" pixel #alues, and di#iding by "he maximum source pixel #alue )i!e! +PP or =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 "he con#ersion func"ion! For ?=:bi" @E%F inpu" images, a clone of "he inpu" is re"urned! For $+<:bi" @E%(F images, con#ersion is done by copying "he source floa" pixel #alues in"o "he des"ina"ion floa" pixel #alues, skipping "he alpha channel!
FreeImage-Convert$o9I:$16
$ ; < $= +; >+ $=7IDT$= ;<@E%$= =;@E%($=
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"o!IN"CD(FIBI")AP 'di-$%
3on#er"s a bi"map "o an unsigned $=:bi" greyscale image )i!e! image whose "ype is FIT67IDT$=*! S"andard bi"maps are firs" con#er"ed )if needed* "o <:bi" greyscale images and "hen con#ersion is done by mul"iplying "he <:bi" channel by +P=! O"her bi"map "ypes are con#er"ed by using a greyscale con#ersion formula! For $=:bi" FIT67IDT$= images, a clone of "he inpu" is re"urned!
When crea"ing "he greyscale uin"$= image from a @E%U(V image, "he luminance L )or greyscale in"ensi"y* of a resul" pixel is calcula"ed from "he s@E% model using a 0=P whi"e poin", using "he @ec!T,? formula 1 L S ) ,!+$+= A r * 9 ) ,!T$P+ A g * 9 ) ,!,T++ A b * The #alues ,!+$+=, ,!T$P+ and ,!,T++ represen" "he rela"i#e red, green, and blue in"ensi"ies!
FreeImage-Convert$o+. 16
$ ; < $= +; >+ $=7IDT$= ;<@E%$= =;@E%($=
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Convert"o!IN"CD(FIBI")AP 'di-$%
3on#er"s a bi"map "o an unsigned $=:bi" @E% image )i!e! image whose "ype is FIT6@E%$=*! S"andard bi"maps are firs" con#er"ed )if needed* "o +;:bi" @E% images and "hen con#ersion is done by mul"iplying "he <:bi" channel by +P=! When an alpha channel is presen" in "he source, i" is simply ignored by "he con#ersion func"ion! For $=:bi" FIT6@E%$= images, a clone of "he inpu" is re"urned!
(ppendi) 3"
$one mapping operators

Tone mapping opera"ors are used "o compress a large range of pixel luminances in"o a smaller range "ha" is sui"able for display on de#ices wi"h limi"ed dynamic range )e!g! display de#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 numbers in"o an image con"aining in"egers in "he range of , "o +PP such "ha" we can display i" on a prin"er or a moni"or! This sugges"s linear scaling as a possible solu"ion! .owe#er, "his approach is flawed because de"ails in "he ligh" or dark areas of "he image will be los" due "o subseCuen" Cuan"iLa"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 "one mapping opera"ors, ha#e been proposed "o accura"ely render .igh 0ynamic @ange images!
FreeImage-$one!apping
;<@E%$= =;@E%($= ?=@E%F $+<@E%(F
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_"one)apping(FIBI")AP 'di-0 F/ _I)A( _")O tmo0 dou-le *irst_param FI_D FA!L"(=$0 dou-le second_param FI_D FA!L"(=$$%
3on#er"s a .igh 0ynamic @ange image );<:bi" @E% or ?=:bi" @E%F* "o a +;:bi" @E% image, sui"able for display! The tmo parame"er specifies "he "one mapping opera"or "o be used! The func"ion firs" con#er"s "he inpu" image "o a ?=:bi" @E%F image )using "he FreeImage63on#er"To@E%F func"ion*! Then, "he bi"map is "one mapped using one of "he following algori"hms1 4arameter
FITMO60@(EO,> FITMO6@2ID.(@0,P FITMO6F(TT(L,+
$one mapping operator

(dap"i#e logari"hmic mapping )F! 0rago, +,,>* 0ynamic range reduc"ion inspired by pho"orecep"or physiology )2! @einhard, +,,P* 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 choosen algori"hm )see "he defini"ion of each "one mapping opera"or below*! When bo"h parame"ers are se" "o Lero, a defaul" se" of parame"ers is used!
++ load a .D/ /(B Float image FIBI")AP 'src 5 FreeImage_Load(FIF_.D/0 FmemorialG&drH0 =$% ++ create a ?@T-it tone mapped image suita-le *or display FIBI")AP 'dst 5 FreeImage_"one)apping(src0 FI")O_D/A(O=>$% ++ : FreeImage_!nload(src$% FreeImage_!nload(dst$%
FreeImage-$moDrago#3
;<@E%$= =;@E%($= ?=@E%F $+<@E%(F
DLL_API FIBI")AP' DLL_CALLCONV FreeImage_"moDrago=>(FIBI")AP 'src0 dou-le gamma FI_D FA!L"(?G?$0 dou-le eVposure FI_D FA!L"(=$$%
3on#er"s a .igh 0ynamic @ange image "o a +;:bi" @E% image using a global opera"or based on logari"hmic compression of luminance #alues, imi"a"ing "he human response "o ligh"! ( bias power func"ion is in"roduced "o adap"i#ely #ary logari"hmic bases, resul"ing in good preser#a"ion of de"ails and con"ras"!
3& (ppendi)
7pon en"ry, gamma )where gamma O ,* is a gamma correc"ion "ha" is applied after "he "one mapping! ( #alue of $ means no correc"ion! The defaul" +!+ #alue, used in "he original au"hor's paper, is recommended as a good s"ar"ing #alue! The exposure parame"er, in "he range U:<, <V, is an exposure scale fac"or allowing users "o ad&us" "he brigh"ness of "he ou"pu" image "o "heir displaying condi"ions! The defaul" #alue ),* means "ha" no correc"ion is applied! .igher #alues will make "he image ligh"er whereas lower #alues make "he image darker! +eference F! 0rago, I! MysLkowski, T! (nnen and D! 3hiba, (dap"i#e logari"hmic mapping for displaying high con"ras" scenes! -roceedings of 2urographics+,,>, 4ol!++, Do, >, pp! ;$?:;+=, +,,>!
FreeImage-$mo+einhard#5
;<@E%$= =;@E%($= ?=@E%F $+<@E%(F
DLL_API FIBI")AP' DLL_CALLCONV FreeImage_"mo/ein&ard=E(FIBI")AP 'src0 dou-le intensity FI_D FA!L"(=$0 dou-le contrast FI_D FA!L"(=$$%
3on#er"s a .igh 0ynamic @ange image "o a +;:bi" @E% image using a global opera"or inspired by pho"orecep"or physiology of "he human #isual sys"em! 7pon en"ry, "he intensity parame"er, in "he range U:<, <V, con"rols "he o#erall image in"ensi"y! The defaul" #alue , means no correc"ion! .igher #alues will make "he image ligh"er whereas lower #alues make "he image darker! The contrast parame"er, in "he range U,!>, $!,U, con"rols "he o#erall image con"ras"! When using "he defaul" #alue ),*, "his parame"er is calcula"ed au"oma"ically! +eference 2! @einhard and I! 0e#lin, 0ynamic @ange @educ"ion Inspired by -ho"orecep"or -hysiology! I222 Transac"ions on 4isualiLa"ion and 3ompu"er Eraphics, $$)$*, Jan8Feb +,,P! 2! @einhard, -arame"er es"ima"ion for pho"ographic "one reproduc"ion, Journal of Eraphics Tools, #ol! T, no! $, pp! ;PYP$, +,,>!
FreeImage-$mo+einhard#5,)
;<@E%$= =;@E%($= ?=@E%F $+<@E%(F
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_"mo/ein&ard=E V(FIBI")AP 'src0 dou-le intensity FI_D FA!L"(=$0 dou-le contrast FI_D FA!L"(=$0 dou-le adaptation FI_D FA!L"(C$0 dou-le color_correction FI_D FA!L"(=$$%
3on#er"s a .igh 0ynamic @ange image "o a +;:bi" @E% image using a global 8 local opera"or inspired by pho"orecep"or physiology of "he human #isual sys"em! 7ser parame"ers con"rol in"ensi"y, con"ras", and le#el of adap"a"ion! 7pon en"ry, "he intensity parame"er, in "he range U:<, <V, con"rols "he o#erall image in"ensi"y! The defaul" #alue , means no correc"ion! .igher #alues will make "he image ligh"er whereas lower #alues make "he image darker! The contrast parame"er, in "he range U,!>, $!,U, con"rols "he o#erall image con"ras"! When using "he defaul" #alue ),*, "his parame"er is calcula"ed au"oma"ically! The adaptation parame"er, in range U,1$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 U,1$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!
(ppendi) 3=
+eference 2! @einhard and I! 0e#lin, 0ynamic @ange @educ"ion Inspired by -ho"orecep"or -hysiology! I222 Transac"ions on 4isualiLa"ion and 3ompu"er Eraphics, $$)$*, Jan8Feb +,,P! 2! @einhard, -arame"er es"ima"ion for pho"ographic "one reproduc"ion, Journal of Eraphics Tools, #ol! T, no! $, pp! ;PYP$, +,,>!
FreeImage-$moFattal#'
;<@E%$= =;@E%($= ?=@E%F $+<@E%(F
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_"moFattal=?(FIBI")AP 'src0 dou-le color_saturation FI_D FA!L"(=GE$0 dou-le attenuation FI_D FA!L"(=GBE$$%
3on#er"s a .igh 0ynamic @ange image "o a +;:bi" @E% image using a local opera"or "ha" manipula"e "he gradien" field of "he luminance image by a""enua"ing "he magni"udes of large gradien"s! ( new, low dynamic range image is "hen ob"ained by sol#ing a -oisson eCua"ion on "he modified gradien" field! 7pon en"ry, "he color_saturation parame"er, in "he range U,!;, ,!=V, con"rols color sa"ura"ion in "he resul"ing image! The attenuation parame"er, in "he range U,!<, ,!?V, con"rols "he amoun" of a""enua"ion! The algori"hm works by sol#ing as many -ar"ial 0ifferen"ial 2Cua"ions as "here are pixels in "he image, using a -oisson sol#er based on a mul"igrid algori"hm! Thus, "he algori"hm may "ake many minu"es )up "o P or more* before "o comple"e! +eference @! Fa""al, 0! Lischinski, and M! Werman, Eradien" domain high dynamic range compression! (3M Transac"ions on Eraphics, +$)>*1+;?Y+P=, +,,+!
5# (ppendi)
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@6IS63MBI "he bi"map is a represen"a"ion of a 3MBI separa"ion! Toge"her wi"h color managemen" "his informa"ion is impor"an", because "he profile da"a and "he bi"map mus" reside in "he same color model )e!g! @E% or 3MBI*! In almos" all cases, "he bi"map is loaded as an @E% represen"a"ion! I" may depend on special flags "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)A6 separated data *rom "IFF (no /(B conversion done$ FIBI")AP '-itmap 5 FreeImage_Load (FIF_"IFF0 name0 "IFF_C)A6$% i* (-itmap$ 1 ++ test *or /(B or C)A6 colour space i* ((FreeImage_(etICCPro*ile(-itmap$TW*lags I FIICC_COLO/_I#_C)A6$ 55 FIICC_COLO/_I#_C)A6$ ++ ;e are in C)A6 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 called safely, when "he original forma" does no" suppor" profiles!
(ppendi) 51
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called J-itmapK ++ retrieve a pointer to FIICCP/OFIL FIICCP/OFIL structure
'pro*ile 5 FreeImage_(etICCPro*ile(-itmap$%
I* (pro*ileTWdata$ 1 ++ pro*ile data present 9
FreeImage-CreateICC4rofile
DLL_API FIICCP/OFIL 'data0 long siLe$% 'DLL_CALLCONV FreeImage_CreateICCPro*ile(FIBI")AP 'di-0 void
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"ion re"urns a poin"er "o "he FII33-@OFIL2 s"ruc"ure crea"ed!
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called J-itmapK D7O/D siLe 5 _*ilelengt&(*ileno(&Pro*ile$$% ++ read pro*ile data *rom *ile and LeroTterminate i* (siLe II (data 5 (void '$malloc(siLe O C$$$ 1 siLe 5 *read(data0 C0 siLe0 &Pro*ile$% '(data O siLe$ 5 =% ++ attac& retrieved pro*ile data to -itmap FIICCP/OFIL 9 *ree (data$% 'pro*ile 5 FreeImage_CreateICCPro*ile (-itmap0 data0 siLe$%
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 "o ensure "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$%
5' (ppendi)
4lugin functions
Through a#erage use you won'" probably no"ice i", FreeImage is plugin dri#en! 2ach bi"map loader8sa#er is in fac" a plugin module "ha" is linked inside "he in"egra"ed plugin manager! Bou won'" 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 is done "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" all bi"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 license res"ric"ions on "hem, such as EIF! In fear "ha" he would pu" all i"s bi"map loaders8sa#ers in "iny 0LLs "ha" would spla""er "he hard dri#e, his mos" impor"an" \cus"omer' s"rongly encouraged him "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 "he main F@22IM(E2!0LL, in ex"ernal 0LLs, and e#en direc"ly in an applica"ion "ha" dri#es FreeImage!
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! In FreeImage F@226IM(E26FO@M(T became, "hrough e#olu"ion, synonymous wi"h plugin!
FreeImage-0et4lugin,nabled
DLL_API int DLL_CALLCONV FreeImage_#etPlugin na-led(F/ ena-le$% _I)A( _FO/)A" *i*0 BOOL
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-Is4lugin,nabled
DLL_API int DLL_CALLCONV FreeImage_IsPlugin na-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!
(ppendi) 53
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"ands for Mul"ipurpose In"erne" Mail 2x"ension*!
F/ _I)A( _FO/)A" *i* 5 FreeImage_(etFIFFrom)ime(Fimage+pngH$% I*(*i* 45 FIF_!N6NO7N$ 1 assert(*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"ands for 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 assigned F@226IM(E26FO@M(T!
FreeImage-.etFIF,)tensionList
DLL_API const c&ar 'DLL_CALLCONV FreeImage_(etFIF VtensionList(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 plugin can read and8or wri"e!
55 (ppendi)
+'' 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 -oV ((etOpenFileName or CFileDialog$G ,param sLFilter Input and output parameterG sLFilter is an array o* c&ar ;&ose lengt& s&ould -e ?=@B or moreG ,return /eturns t&e num-er o* supported import *ormats '+ int (etOpenFilter#tring(c&ar 'sLFilter$ 1 int i0 iCount% c&ar FilterP?=@BQ% c&ar 'to<en% ++ Build a string *or YAll image *ilesY FilterP=Q 5 Y3=Y% *or(i 5 =% i N FreeImage_(etFIFCount($% iOO$ 1 i*(FreeImage_FIF#upports/eading((F/ _I)A( _FO/)A"$i$$ 1 strcat(Filter0 FreeImage_(etFIF VtensionList((F/ _I)A( _FO/)A"$i$$% strcat(Filter0 202$% 9 9 FilterPstrlen(Filter$TCQ 5 Y3=Y% strcpy(sLFilter0 2All image *iles_2$% to<en 5 strto<(Filter0 202$% ;&ile(to<en 45 N!LL$ 1 strcat(sLFilter0 2'G2$% strcat(sLFilter0 to<en$% strcat(sLFilter0 2%2$% ++ get neVt to<en to<en 5 strto<(N!LL0 202$% 9 sLFilterPstrlen(sLFilter$TCQ 5 Y_Y% ++ Build a string *or YAll *ilesY strcat(sLFilter0 2All Files ('G'$_'G'_2$% ++ Build a string *or eac& *ormat FilterP=Q 5 Y3=Y% iCount 5 =% *or(i 5 =% i N FreeImage_(etFIFCount($% iOO$ 1 i*(FreeImage_FIF#upports/eading((F/ _I)A( _FO/)A"$i$$ 1 ++ Description sprint*(Filter0 28s (8s$_20 FreeImage_(etFIFDescription((F/ _I)A( _FO/)A"$i$0 FreeImage_(etFIF VtensionList((F/ _I)A( _FO/)A"$i$$% strcat(sLFilter0 Filter$% ++ Vtension(s$ strcpy(Filter0 FreeImage_(etFIF VtensionList((F/ _I)A( _FO/)A"$i$$% to<en 5 strto<(Filter0 202$% ;&ile(to<en 45 N!LL$ 1 strcat(sLFilter0 2'G2$% strcat(sLFilter0 to<en$% strcat(sLFilter0 2%2$% ++ get neVt to<en to<en 5 strto<(N!LL0 202$% 9 sLFilterPstrlen(sLFilter$TCQ 5 Y_Y% iCountOO% 9 9 strcat(sLFilter0 2_2$% 9 return iCount%
FreeImage-.etFIFDescription
DLL_API const c&ar 'DLL_CALLCONV FreeImage_(etFIFDescription(F/ _I)A( _FO/)A" *i*$%
@e"urns a descrip"i#e s"ring "ha" describes "he bi"map forma"s "he gi#en plugin can read and8or wri"e!
FreeImage-.etFIF+eg,)pr
DLL_API const c&ar ' DLL_CALLCONV FreeImage_(etFIF/eg Vpr(F/ _I)A( _FO/)A" *i*$%
(ppendi) 55
@e"urns a regular expression s"ring "ha" can be used by a regular expression engine "o iden"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"e files wi"h "ha" ex"ension in "he form of a F@226IM(E26FO@M(T iden"ifier!
+'' (eneric image loader ,param lpsLPat&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' lpsLPat&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(lpsLPat&Name0 =$% i*(*i* 55 FIF_!N6NO7N$ 1 ++ no signature \ ++ try to guess t&e *ile *ormat *rom t&e *ile eVtension *i* 5 FreeImage_(etFIFFromFilename(lpsLPat&Name$% 9 ++ c&ec< t&at t&e plugin &as reading capa-ilities GGG i*((*i* 45 FIF_!N6NO7N$ II FreeImage_FIF#upports/eading(*i*$$ 1 ++ o<0 letYs load t&e *ile FIBI")AP 'di- 5 FreeImage_Load(*i*0 lpsLPat&Name0 *lag$% ++ unless a -ad *ile *ormat0 ;e are done 4 return di-% 9 return N!LL% 9
FreeImage-.etFIFFromFilename9
DLL_API F/ _I)A( _FO/)A" DLL_CALLCONV FreeImage_(etFIFFromFilename!(const ;c&ar_t '*ilename$%
This func"ion works exac"ly like FreeImage6Ee"FIFFromFilename 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"ion does no"hing and re"urns FIF67DIDOWD!
FreeImage-FIF0upports+eading
DLL_API BOOL DLL_CALLCONV FreeImage_FIF#upports/eading(F/ _I)A( _FO/)A" *i*$%
@e"urns T@72 if "he plugin belonging "o "he gi#en F@226IM(E26FO@M(T can be used "o load bi"maps, F(LS2 o"herwise!
FreeImage-FIF0upportsEriting
DLL_API BOOL DLL_CALLCONV FreeImage_FIF#upports7riting(F/ _I)A( _FO/)A" *i*$%
@e"urns T@72 if "he plugin belonging "o "he gi#en F@226IM(E26FO@M(T can be used "o sa#e bi"maps, F(LS2 o"herwise!
56 (ppendi)
+'' (eneric image ;riter ,param di- Pointer to t&e di- to -e saved ,param lpsLPat&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' lpsLPat&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 eVtension *i* 5 FreeImage_(etFIFFromFilename(lpsLPat&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( _"AP 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 eVport capa-ilities GGG 7O/D -pp 5 FreeImage_(etBPP(di-$% -Can#ave 5 (FreeImage_FIF#upports7riting(*i*$ II FreeImage_FIF#upports VportBPP(*i*0 -pp$$% 9 else 1 ++ special -itmap type ++ c&ec< t&at t&e plugin &as su**icient eVport capa-ilities -Can#ave 5 FreeImage_FIF#upports Vport"ype(*i*0 image_type$% 9 i*(-Can#ave$ 1 -#uccess 5 FreeImage_#ave(*i*0 di-0 lpsLPat&Name0 *lag$% 9
9 return (-#uccess 55 "/! $ \ true X *alse%
FreeImage-FIF0upports,)port$ype
DLL_API BOOL DLL_CALLCONV FreeImage_FIF#upports Vport"ype(F/ F/ _I)A( _"AP type$% _I)A( _FO/)A" *i*0
@e"urns T@72 if "he plugin belonging "o "he gi#en F@226IM(E26FO@M(T can sa#e a bi"map in "he desired da"a "ype, re"urns F(LS2 o"herwise! See "he lis" of Suppor"ed file forma"s in "he appendix for a lis" of plugins "ha" can sa#e non:s"andard images!
FreeImage-FIF0upports,)port 44
$ ; < $= +; >+
_I)A( _FO/)A" *i*0 int DLL_API BOOL DLL_CALLCONV FreeImage_FIF#upports VportBPP(F/ -pp$%
@e"urns T@72 if "he plugin belonging "o "he gi#en F@226IM(E26FO@M(T can sa#e a bi"map in "he desired bi" dep"h, re"urns F(LS2 o"herwise!
(ppendi) 5"
+'' 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 -oV ((et#aveFileName or CFileDialog$G ,param sLFilter Input and output parametersG sLFilter is an array o* c&ar ;&ose lengt& s&ould -e ?=@B 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 eVport *ormats '+ int (et#aveAsFilter#tring(c&ar 'sLFilter0 7O/D -pp0 F/ _I)A( _"AP image_type$ 1 int i0 iCount% c&ar FilterP?=@BQ% c&ar 'to<en% sLFilterP=Q 5 Y3=Y% iCount 5 =% ++ Build a string *or eac& *ormat *or(i 5 =% i N FreeImage_(etFIFCount($% iOO$ 1 ++ C&ec< t&at t&e di- can -e saved in t&is *ormat BOOL -Can#ave% F/ _I)A( _FO/)A" *i* 5 (F/ _I)A( _FO/)A"$i%
i*(image_type 55 FI"_BI")AP$ 1 ++ standard -itmap type -Can#ave 5 (FreeImage_FIF#upports7riting(*i*$ II FreeImage_FIF#upports VportBPP(*i*0 -pp$$% 9 else 1 ++ special -itmap type -Can#ave 5 FreeImage_FIF#upports Vport"ype(*i*0 image_type$% 9 i*(-Can#ave$ 1 ++ .andle t&e special case o* PN) *iles strcpy(Filter0 FreeImage_(etFormatFromFIF((F/ _I)A( _FO/)A"$i$$% i*((-pp 55 C$ II (4strncmp(Filter0 2P()20 >$ __ 4strncmp(Filter0 2PP)20 >$$$ continue% i*((-pp 55 B$ II (4strncmp(Filter0 2PB)20 >$ __ 4strncmp(Filter0 2PP)20 >$$$ continue% i*((-pp 55 ?@$ II (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_(etFIF VtensionList((F/ _I)A( _FO/)A"$i$$% strcat(sLFilter0 Filter$% ++ Vtension(s$ strcpy(Filter0 FreeImage_(etFIF VtensionList((F/ _I)A( _FO/)A"$i$$% to<en 5 strto<(Filter0 202$% ;&ile(to<en 45 N!LL$ 1 strcat(sLFilter0 2'G2$% strcat(sLFilter0 to<en$% strcat(sLFilter0 2%2$% ++ get neVt to<en to<en 5 strto<(N!LL0 202$% 9 sLFilterPstrlen(sLFilter$TCQ 5 Y_Y% iCountOO%
9 9 strcat(sLFilter0 2_2$% return iCount%
FreeImage-FIF0upportsICC4rofiles
DLL_API BOOL DLL_CALLCONV FreeImage_FIF#upportsICCPro*iles(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 or sa#e an I33 profile, re"urns F(LS2 o"herwise!
5& (ppendi)
++ 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#upportsNoPiVels(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 file using "he FIF6LO(06DO-I 2LS load flag! If T@72, a loader can load header only da"a and possibly some me"ada"aM
++ determine0 ;&et&er J&eader onlyK support is present i* (FreeImage_FIF#upportsNoPiVels(FIF_ZP ($$ 1 ++ J&eader onlyK support present 9
FreeImage-+egisterLocal4lugin
DLL_API F/ _I)A( _FO/)A" DLL_CALLCONV FreeImage_/egisterLocalPlugin(FI_InitProc proc_address0 const c&ar '*ormat FI_D FA!L"(=$0 const c&ar 'description FI_D FA!L"(=$0 const c&ar 'eVtension FI_D FA!L"(=$0 const c&ar 'regeVpr FI_D FA!L"(=$$%
@egis"ers a new plugin "o be used in FreeImage! The plugin is residing direc"ly in "he applica"ion dri#ing FreeImage! The firs" parame"er is a poin"er "o a func"ion "ha" is used "o ini"ialise "he plugin! The ini"ialiLa"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!
(ppendi) 5=
static int s_*ormat_id% void stdcall Init(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 eVample0 a plugin t&at loads ++ B)Ps returns t&e string FB)PHG pluginTW*ormat_proc 5 Format% ++ pointer to a *unction t&at returns a descriptive ++ string *or t&e -itmap typeG For eVample0 a plugin ++ t&at loads B)Ps may return F7indo;s or O#+? BitmapH pluginTWdescription_proc 5 Description% ++ pointer to a *unction t&at returns a comma delimited ++ list o* possi-le *ile eVtension t&at are valid *or ++ t&is pluginG A ZP ( plugin ;ould return F[peg0[i*0[*i*H pluginTWeVtension_proc 5 Vtension%
++ 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<ing at t&e *irst *e; -ytes o* t&e -itmapG 9 pluginTWvalidate_proc 5 Validate%
FreeImage-+egister,)ternal4lugin
DLL_API F/ _I)A( _FO/)A" DLL_CALLCONV FreeImage_/egister VternalPlugin(const c&ar 'pat&0 const c&ar '*ormat FI_D FA!L"(=$0 const c&ar 'description FI_D FA!L"(=$0 const c&ar 'eVtension FI_D FA!L"(=$0 const c&ar 'regeVpr FI_D FA!L"(=$$%
@egis"ers a new plugin "o be used in FreeImage! The plugin is residing in a 0LL! Func"ionally "his func"ion is "he same as FreeImage6@egis"erLocal-lugin, bu" now FreeImage calls an Ini" func"ion in a 0LL ins"ead of a local func"ion in an applica"ion! The Ini" func"ion mus" be called FIni"G and mus" use "he s"dcall calling con#en"ion!
5# (ppendi)
!ultipage functions
FreeImage fea"ures a se" of func"ions "ha" can be used "o manipula"e pages in a mul"i:page bi"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 and change "he order of pages! (ll of "his is offered wi"h a minimum implemen"a"ion in a plugin and 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!ulti itmap
DLL_API FI)!L"IBI")AP ' DLL_CALLCONV FreeImage_Open)ultiBitmap(F/ _I)A( _FO/)A" *i*0 const c&ar '*ilename0 BOOL create_ne;0 BOOL read_only0 BOOL <eep_cac&e_in_memory FI_D FA!L"(FAL# $0 int *lags FI_D FA!L"(=$$%
Opens a mul"i:page bi"map! The firs" parame"er "ells FreeImage "he bi"map:"ype of bi"map "o be opened! 3urren"ly FIF6TIFF, FIF6I3O and FIF6EIF are suppor"ed! The second parame"er specifies "he name of "he bi"map! When "he "hird parame"er is T@72, i" means "ha" a new bi"map will be crea"ed ra"her "han an exis"ing one being opened! When "he four"h parame"er is T@72 "he bi"map is opened read:only! The keep6cache6in6memory parame"er is one purely for performance! When i" is T@72, all ga"hered bi"map da"a in "he page manipula"ion process is kep" in memory, o"herwise i" is laLily flushed "o a "emporary file on "he hard disk in =; Ib blocks! Do"e "ha" depending on "he amoun" of manipula"ion being performed and "he siLe of "he bi"map, "he "emporary da"a can become Cui"e large! I"'s ad#ised "o laLily flush "o disc! 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!
FreeImage-/pen!ulti itmapFrom<andle
DLL_API FI)!L"IBI")AP ' DLL_CALLCONV FreeImage_Open)ultiBitmapFrom.andle(F/ &andle0 int *lags FI_D FA!L"(=$$% _I)A( _FO/)A" *i*0 FreeImageIO 'io0 *i_&andle
This func"ion le"s one open an exis"ing mul"i:page bi"map from a handle in read(only mode! (s wi"h FreeImage6LoadFrom.andle, a poin"er "o a FreeImageIO s"ruc"ure and a fi6handle mus" be specified! The ac"ual implemen"a"ion of FreeImage63loseMul"i%i"map is sufficien", "o close such a mul"ipage bi"map opened from a handle! (l"ough "he source handle is opened in read:only mode, using "his func"ion, mul"i:page handles suppor" read or read8 rite opera"ions! When you modify a mul"i:page file 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 a memory cac'e so "ha" "hese changes can be la"er sa#ed "o an ou"pu" s"ream! The source s"ream is lef" unmodified1 closing "he source s"ream will no" change i"! Bou "hus need "o use a kind of Fsa#e as HG func"ion "o sa#e your changes!
(ppendi) 51
static unsigned DLL_CALLCONV my/eadProc(void '-u**er0 unsigned siLe0 unsigned count0 *i_&andle &andle$ 1 return (unsigned$*read(-u**er0 siLe0 count0 (FIL '$&andle$% 9 static unsigned DLL_CALLCONV my7riteProc(void '-u**er0 unsigned siLe0 unsigned count0 *i_&andle &andle$ 1 return (unsigned$*;rite(-u**er0 siLe0 count0 (FIL '$&andle$% 9 static int DLL_CALLCONV my#ee<Proc(*i_&andle &andle0 long o**set0 int origin$ 1 return *see<((FIL '$&andle0 o**set0 origin$% 9 static long DLL_CALLCONV my"ellProc(*i_&andle &andle$ 1 return *tell((FIL '$&andle$% 9 BOOL test#tream)ultiPageOpen(const c&ar 'input0 int *lags$ 1 ++ initialiLe your o;n IO *unctions FreeImageIO io% ioGread_proc ioG;rite_proc ioGsee<_proc ioGtell_proc 5 5 5 5 my/eadProc% my7riteProc% my#ee<Proc% my"ellProc%
BOOL -#uccess 5 FAL# % ++ Open src stream in readTonly mode FIL '*ile 5 *open(input0 2rO-2$% i* (*ile 45 N!LL$ 1 ++ Open t&e multiTpage *ile F/ _I)A( _FO/)A" *i* 5 FreeImage_(etFile"ypeFrom.andle(Iio0 (*i_&andle$*ile$% FI)!L"IBI")AP 'src 5 FreeImage_Open)ultiBitmapFrom.andle(*i*0 Iio0 (*i_&andle$*ile0 *lags$% i*(src$ 1 ++ get t&e page count int count 5 FreeImage_(etPageCount(src$% assert(count W C$% ++ delete page = (modi*ications are stored to t&e cac&e$ FreeImage_DeletePage(src0 =$% // 'lose s!c file (not%ing is $one) t%e cac%e is clea!e$* -#uccess 5 FreeImage_Close)ultiBitmap(src0 =$% assert(-#uccess$%
++ Close t&e src stream *close(*ile$% 9 9 return -#uccess%
return -#uccess%
FreeImage-0ave!ulti itmap$o<andle
DLL_API BOOL DLL_CALLCONV FreeImage_#ave)ultiBitmap"o.andle(F/ _I)A( _FO/)A" *i*0 FI)!L"IBI")AP '-itmap0 FreeImageIO 'io0 *i_&andle &andle0 int *lags FI_D FA!L"(=$$%
Sa#es a mul"i:page bi"map in"o "he specified handle! The handle mus" be se" "o "he correc" posi"ion before calling "he func"ion! (s wi"h FreeImage6Sa#eTo.andle, a poin"er "o a FreeImageIO s"ruc"ure and a fi6handle mus" be specified!
5' (ppendi)
BOOL test#tream)ultiPage#ave(const c&ar 'input0 const c&ar 'output0 int input_*lag0 int output_*lag$ 1 ++ initialiLe your o;n IO *unctions FreeImageIO io% ioGread_proc ioG;rite_proc ioGsee<_proc ioGtell_proc 5 5 5 5 my/eadProc% my7riteProc% my#ee<Proc% my"ellProc%
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&e0 input_*lag$% i*(src$ 1 ++ Open dst stream in read+;rite mode FIL '*ile 5 *open(output0 2;O-2$% i* (*ile 45 N!LL$ 1 ++ #ave t&e multiTpage *ile to t&e stream BOOL -#uccess 5 FreeImage_#ave)ultiBitmap"o.andle(*i*0 src0 Iio0 (*i_&andle$*ile0 output_*lag$% assert(-#uccess$% ++ Close t&e dst stream *close(*ile$% ++ Close src *ile FreeImage_Close)ultiBitmap(src0 =$% 9 return "/! %
9 9
++ Close src FreeImage_Close)ultiBitmap(src0 =$%
return FAL# %
The following sample shows how "o modify an inpu" s"ream and sa#e your modifica"ions in"o an ou"pu" s"ream! Do"e "ha" "he inpu" s"ream is lef" unchanged1 all modifica"ions are s"ored in"o a cacheM "his cache is "hen used "o apply your modifica"ion on sa#ing!
(ppendi) 53
BOOL test#tream)ultiPageOpen#ave(const c&ar 'input0 const c&ar 'output0 int input_*lag0 int output_*lag$ 1 ++ initialiLe your o;n IO *unctions FreeImageIO io% ioGread_proc ioG;rite_proc ioGsee<_proc ioGtell_proc 5 5 5 5 my/eadProc% my7riteProc% my#ee<Proc% my"ellProc%
BOOL -#uccess 5 FAL# % ++ Open src stream in readTonly mode FIL 'src_*ile 5 *open(input0 2rO-2$% assert(src_*ile$% i* (src_*ile 45 N!LL$ 1 ++ Open t&e multiTpage *ile F/ _I)A( _FO/)A" *i* 5 FreeImage_(etFile"ypeFrom.andle(Iio0 (*i_&andle$src_*ile$% FI)!L"IBI")AP 'src 5 FreeImage_Open)ultiBitmapFrom.andle(*i*0 Iio0 (*i_&andle$src_*ile0 input_*lag$% 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<Page(src0 ?$% i*(di-$ 1 FreeImage_Invert(di-$% ++ !nload t&e -itmap (apply c&ange to src0 modi*ications are stored to t&e 9 FreeImage_!nloc<Page(src0 di-0 "/! $%
cac&e$
++ delete page = (modi*ications are stored to t&e cac&e$ FreeImage_DeletePage(src0 =$% ++ insert a ne; page at position Y=Y (modi*ications are stored to t&e cac&e$ FIBI")AP 'page 5 create]onePlateImage(EC?0 EC?0 C?B$% FreeImage_InsertPage(src0 =0 page$% FreeImage_!nload(page$% ++ Open dst stream in read+;rite mode FIL 'dst_*ile 5 *open(output0 2;O-2$% assert(dst_*ile$% i* (dst_*ile 45 N!LL$ 1 ++ #ave t&e multiTpage *ile to t&e stream (modi*ications are applied$ BOOL -#uccess 5 FreeImage_#ave)ultiBitmap"o.andle(*i*0 src0 Iio0 (*i_&andle$dst_*ile0 output_*lag$% assert(-#uccess$% ++ Close t&e dst stream *close(dst_*ile$%
// 'lose s!c file (not%ing is $one) t%e cac%e is clea!e$* -#uccess 5 FreeImage_Close)ultiBitmap(src0 =$% assert(-#uccess$%
++ Close t&e src stream *close(src_*ile$% 9 9 return -#uccess%
return FAL# %
FreeImage-Close!ulti itmap
DLL_API BOOL DLL_CALLCONV FreeImage_Close)ultiBitmap(FI)!L"IBI")AP '-itmap0 int *lags FI_D FA!L"(=$$%
55 (ppendi)
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#e parame"ers "o change "he sa#ing beha#iour! When "he parame"er is no" a#ailable or unused you can pass "he #alue , or NTB-26OF6%ITM(-O602F(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 page0 FIBI")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<Page(FI)!L"IBI")AP '-itmap0 int page$%
Locks a page in memory for edi"ing! The page can now be sa#ed "o a differen" file or inser"ed in"o ano"her mul"i:page bi"map! When you are done wi"h "he bi"map you ha#e "o call FreeImage67nlock-age "o gi#e "he page back "o "he bi"map and8or apply any changes made in "he page! I" is forbidden "o use FreeImage_Unload on a locked page1 you mus" use FreeImage_Unloc!#age ins"ead!
FreeImage-9nloc%4age
DLL_API void DLL_CALLCONV FreeImage_!nloc<Page(FI)!L"IBI")AP '-itmap0 FIBI")AP 'data0 BOOL c&anged$%
(ppendi) 55
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 "he mul"i:page bi"map!
-ool Clone)ultiPage(F/ 1
_I)A( _FO/)A" *i*0 c&ar 'input0 c&ar 'output0 int output_*lag$
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 N count% pageOO$ 1 ++ Load t&e -itmap at position YpageY FIBI")AP 'di- 5 FreeImage_Loc<Page(src0 page$% i*(di-$ 1 ++ add a ne; -itmap to dst FreeImage_AppendPage(dst0 di-$% ++ !nload t&e -itmap (do not apply any c&ange to src$ FreeImage_!nloc<Page(src0 di-0 FAL# $% 9 9 ++ Close src FreeImage_Close)ultiBitmap(src0 =$% ++ #ave and close dst FreeImage_Close)ultiBitmap(dst0 output_*lag$% 9 9 return true%
return *alse%
FreeImage-!ove4age
DLL_API BOOL DLL_CALLCONV FreeImage_)ovePage(FI)!L"IBI")AP '-itmap0 int target0 int source$%
Mo#es "he source page "o "he posi"ion of "he "arge" page! @e"urns T@72 on success, F(LS2 on failure!
FreeImage-.etLoc%ed4age:umbers
DLL_API BOOL DLL_CALLCONV FreeImage_(etLoc<edPageNum-ers(FI)!L"IBI")AP '-itmap0 int 'pages0 int 'count$%
@e"urns an array of page:numbers "ha" are curren"ly locked in memory! When "he pages parame"er is D7LL, "he siLe of "he array is re"urned in "he coun" #ariable! Bou can "hen alloca"e "he array of "he desired siLe and call FreeImage6Ee"Locked-ageDumbers again "o popula"e "he array!
56 (ppendi)
!emory IG/ streams

Memory I8O rou"ines use a specialiLed #ersion of "he FreeImageIO s"ruc"ure, "arge"ed "o sa#e8load FI%ITM(- images "o8from a memory s"ream! Jus" like you would do wi"h a file s"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 "o wri"e image files "o a In"erne" s"ream!
FreeImage-/pen!emory
DLL_API FI) )O/A 'DLL_CALLCONV FreeImage_Open)emory(BA" siLe_in_-ytes FI_D FA!L"(=$$% 'data FI_D FA!L"(=$0 D7O/D
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"e access! The s"ream will suppor" loading and sa#ing of FI%ITM(- in a memory file )managed in"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#ing FreeImage! ( buffer con"aining image da"a is gi#en as func"ion argumen"s data )s"ar" of "he buffer* and si"e_in_)ytes )buffer siLe in by"es*! ( memory buffer wrapped by FreeImage is read only! Images can be loaded bu" canno" be sa#ed!
FreeImage-Close!emory
DLL_API void DLL_CALLCONV FreeImage_Close)emory(FI) )O/A '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/ FI) )O/A 'stream0 int *lags FI_D FA!L"(=$$% _I)A( _FO/)A" *i*0
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 possible F@226IM(E26FO@M(T cons"an"s is a#ailable in Table $*! The second parame"er "ells FreeImage "he memory s"ream i" has "o decode! 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! 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 , or NTB-26OF6%ITM(-O602F(7LT )e!g! %M-602F(7LT, I3O602F(7LT, e"c*!
(ppendi) 5"
void testLoad)emIO(const c&ar 'lpsLPat&Name$ 1 struct stat -u*% int result% ++ get data associated ;it& lpsLPat&Name result 5 stat(lpsLPat&Name0 I-u*$% i*(result 55 =$ 1 ++ allocate a memory -u**er and load temporary data BA" 'mem_-u**er 5 (BA" '$malloc(-u*Gst_siLe ' siLeo*(BA" $$% i*(mem_-u**er$ 1 FIL 'stream 5 *open(lpsLPat&Name0 2r-2$% i*(stream$ 1 *read(mem_-u**er0 siLeo*(BA" $0 -u*Gst_siLe0 stream$% *close(stream$% ++ attac& t&e -inary data to a memory stream FI) )O/A '&mem 5 FreeImage_Open)emory(mem_-u**er0 -u*Gst_siLe$% ++ 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_PN(0 c&ec<0 2-lo-Gpng20 PN(_D FA!L"$% FreeImage_!nload(c&ec<$% ++ al+ays close t%e "e"o!y st!ea" FreeImage_Close)emory(&mem$% 9 9 ++ user is responsi-le *or *reeing t&e data *ree(mem_-u**er$%
FreeImage-0ave$o!emory
DLL_API BOOL DLL_CALLCONV FreeImage_#ave"o)emory(F/ FI) )O/A 'stream0 int *lags FI_D FA!L"(=$$% _I)A( _FO/)A" *i*0 FIBI")AP 'di-0
This func"ion does for memory s"reams wha" FreeImage6Sa#e does for file s"reams! FreeImage6Sa#eToMemory sa#es a pre#iously loaded FI%ITM(- "o a memory file managed by FreeImage! The firs" parame"er defines "he "ype of "he bi"map "o be sa#ed! For example, when FIF6%M- is passed, a %M- file is sa#ed )an o#er#iew of possible F@226IM(E26FO@M(T cons"an"s is a#ailable in Table $*! The second parame"er is "he memory s"ream where "he bi"map mus" be sa#ed! When "he memory file poin"er poin" "o "he beginning of "he memory file, any exis"ing da"a is o#erwri""en! O"herwise, you can sa#e mul"iple images on "he same s"ream! Do"e "ha" some bi"map sa#e plugins ha#e res"ric"ions on "he bi"map "ypes "hey can sa#e! For example, "he J-2E plugin can only sa#e +;:bi" and <:bi" greyscale bi"maps! 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! Some bi"map sa#ers can recei#e parame"ers "o change "he sa#ing beha#iour )see Table ;*! When "he parame"er is no" a#ailable or unused you can pass "he #alue , or NTB-26OF6%ITM(-O602F(7LT )e!g! %M-602F(7LT, I3O602F(7LT, e"c*!
5& (ppendi)
void test#ave)emIO(const c&ar 'lpsLPat&Name$ 1 FI) )O/A '&mem 5 N!LL% ++ load and decode a regular *ile F/ _I)A( _FO/)A" *i* 5 FreeImage_(etFile"ype(lpsLPat&Name$% FIBI")AP 'di- 5 FreeImage_Load(*i*0 lpsLPat&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_siLe long *ile_siLe 5 FreeImage_"ell)emory(&mem$% print*(2File siLe X 8ld3n20 *ile_siLe$% ++ its easy to load an image *rom memory as ;ell ++ see< to t&e start o* t&e memory stream FreeImage_#ee<)emory(&mem0 =L0 # 6_# "$% ++ get t&e *ile type F/ _I)A( _FO/)A" mem_*i* 5 FreeImage_(etFile"ypeFrom)emory(&mem0 =$% ++ load an image *rom t&e memory &andle FIBI")AP 'c&ec< 5 FreeImage_LoadFrom)emory(mem_*i*0 &mem0 =$% ++ save as a regular *ile FreeImage_#ave(FIF_PN(0 c&ec<0 2dumpGpng20 PN(_D FA!L"$% ++ ma<e sure to close t%e st!ea" since FreeImage_#ave"o)emory ++ ;ill cause internal memory allocations and t&is is t&e only ++ ;ay to *ree t&is allocated memory FreeImage_Close)emory(&mem$% FreeImage_!nload(c&ec<$% FreeImage_!nload(di-$%
FreeImage-(cHuire!emory
DLL_API BOOL DLL_CALLCONV FreeImage_AcUuire)emory(FI) )O/A 'stream0 BA" 'siLe_in_-ytes$% ''data0 D7O/D
-ro#ides a direc" buffer access "o a memory s"ream! 7pon en"ry, stream is "he "arge" memory s"ream, re"urned #alue data is a poin"er "o "he memory buffer, re"urned #alue si"e_in_)ytes is "he buffer siLe in by"es! The func"ion re"urns T@72 if successful, F(LS2 o"herwise!
When "he memory s"ream is managed in"ernally by FreeImage, "he da"a poin"er re"urned by FreeImage_*c+uire,emory may become in#alid as soon as you call FreeImage6Sa#eToMemory!
(ppendi) 5=
void testAcUuire)emIO(const c&ar 'lpsLPat&Name$ 1 FI) )O/A '&mem 5 N!LL% ++ load a regular *ile F/ _I)A( _FO/)A" *i* 5 FreeImage_(etFile"ype(lpsLPat&Name$% FIBI")AP 'di- 5 FreeImage_Load(*i*0 lpsLPat&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_PN(0 di-0 &mem0 PN(_D FA!L"$% FreeImage_!nload(di-$% ++ get t&e -u**er *rom t&e memory stream BA" 'mem_-u**er 5 N!LL% D7O/D siLe_in_-ytes 5 =% FreeImage_AcUuire)emory(&mem0 Imem_-u**er0 IsiLe_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 siLeo*(BA" $0 siLe_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/A 'stream$%
Ee"s "he curren" posi"ion of a memory poin"er! 7pon en"ry, stream is "he "arge" memory s"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<)emory(FI) )O/A 'stream0 long o**set0 int origin$%
Mo#es "he memory poin"er "o a specified loca"ion! -arame"ers follows1 s"ream -oin"er "o "he "arge" memory s"ream offse" origin Dumber of by"es from origin Ini"ial posi"ion
The func"ion re"urns T@72 if successful, re"urns F(LS2 o"herwise The FreeImage_$ee!,emory func"ion mo#es "he memory file poin"er )if any* associa"ed wi"h stream "o a new loca"ion "ha" is offset by"es from origin! The nex" opera"ion on "he s"ream "akes place a" "he new loca"ion! On a s"ream managed by FreeImage, "he nex" opera"ion can be ei"her a read or a wri"e! The argumen" origin mus" be one of "he following cons"an"s, defined in ST0IO!. )and also in FreeImage!h* 1 S22I637@ S22I62D0 S22I6S2T 3urren" posi"ion of file poin"er! 2nd of file! %eginning of file!
6# (ppendi)
FreeImage-+ead!emory
DLL_API unsigned DLL_CALLCONV FreeImage_/ead)emory(void '-u**er0 unsigned siLe0 unsigned count0 FI) )O/A 'stream$%
@eads da"a from a memory s"ream! The FreeImage6@eadMemory func"ion reads up "o count i"ems of si"e by"es from "he inpu" memory s"ream and s"ores "hem in )uffer! The memory poin"er associa"ed wi"h stream is increased 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 count if an error 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 siLe0 unsigned count0 FI) )O/A '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, from )uffer "o "he ou"pu" memory s"ream! The memory poin"er associa"ed wi"h stream is incremen"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 count if an error occurs!
FreeImage_%ead,emory and FreeImage_Write,emory are useful whene#er you need a memory s"ream "o s"ore "emporary da"a! When combined wi"h FreeImage_$ee!,emory and FreeImage_-ell,emory, "his represen"s an al"erna"i#e "o "he use of "emporary files!
FreeImage-Load!ulti itmapFrom!emory
DLL_API FI)!L"IBI")AP 'DLL_CALLCONV FreeImage_Load)ultiBitmapFrom)emory(F/ FI_D FA!L"(=$$% _I)A( _FO/)A" *i*0 FI) )O/A 'stream0 int *lags
Open a mul"i:page bi"map from a memory s"ream! This func"ion is similar "o "he FreeImage6OpenMul"i%i"map func"ion, wi"h "he difference "ha" you will be able "o open a mul"i:page file, in read(only 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"ly FIF6TIFF, FIF6I3O and FIF6EIF are suppor"ed! The second parame"er "ells FreeImage "he memory s"ream i" has "o decode! 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! (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:page file 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 a memory cache so "ha" "hese changes can be la"er sa#ed "o an ou"pu" s"ream! The source memory s"ream is lef" unmodified1 closing "he source s"ream will no" change i"! Bou "hus need "o use a kind of Fsa#e as HG func"ion "o sa#e your changes!
(ppendi) 61
static BOOL eVtractPagesFrom)emory(F/ _I)A( _FO/)A" *i*0 FI) )O/A 'stream$ 1 c&ar *ilenameP?EDQ% ++ 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$% ++ eVtract all pages *or(int page 5 =% page N count% pageOO$ 1 ++ load t&e -itmap at position YpageY FIBI")AP 'di- 5 FreeImage_Loc<Page(src0 page$% i*(di-$ 1 ++ save t&e page sprint*(*ilename0 2page8dG8s20 page0 FreeImage_(etFormatFromFIF(*i*$$% FreeImage_#ave(*i*0 di-0 *ilename0 =$% ++ !nload t&e -itmap (do not apply any c&ange to src$ FreeImage_!nloc<Page(src0 di-0 FAL# $% 9 else 1 ++ an error occuredX *ree t&e multipage -itmap &andle and return FreeImage_Close)ultiBitmap(src0 =$% return FAL# % 9 9 9 // "a1e su!e to close t%e "ultipage &it"ap %an$le on exit return FreeImage_Close)ultiBitmap(src0 =$% 9 void testLoad)ultiBitmapFrom)emory(const c&ar 'lpsLPat&Name$ 1 struct stat -u*% int result% ++ get data associated ;it& lpsLPat&Name result 5 stat(lpsLPat&Name0 I-u*$% i*(result 55 =$ 1 ++ allocate a memory -u**er and load temporary data BA" 'mem_-u**er 5 (BA" '$malloc(-u*Gst_siLe ' siLeo*(BA" $$% i*(mem_-u**er$ 1 FIL 'stream 5 *open(lpsLPat&Name0 2r-2$% i*(stream$ 1 *read(mem_-u**er0 siLeo*(BA" $0 -u*Gst_siLe0 stream$% *close(stream$% ++ attac& t&e -inary data to a memory stream FI) )O/A '&mem 5 FreeImage_Open)emory(mem_-u**er0 -u*Gst_siLe$% ++ get t&e *ile type F/ _I)A( _FO/)A" *i* 5 FreeImage_(etFile"ypeFrom)emory(&mem0 =$% ++ eVtract pages .OOL &Success = ext!actPagesF!o",e"o!y(fif) %"e"*; assert(-#uccess$% // close t%e st!ea" FreeImage_Close)emory(&mem$% 9 9 ++ user is responsi-le *or *reeing t&e data *ree(mem_-u**er$%
FreeImage-0ave!ulti itmap$o!emory
DLL_API BOOL DLL_CALLCONV FreeImage_#ave)ultiBitmap"o)emory(F/ FI)!L"IBI")AP '-itmap0 FI) )O/A 'stream0 int *lags$% _I)A( _FO/)A" *i*0
Sa#es a mul"i:page bi"map in"o "he specified memory handle! The handle mus" be se" "o "he correc" posi"ion before calling "he func"ion!
6' (ppendi)
BOOL test#ave)ultiBitmap"o)emory(const c&ar 'input0 const c&ar 'output0 int output_*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/A 'dst_memory 5 FreeImage_Open)emory($% ++ save t&e *ile to memory &Success = F!eeI"age_Sa e,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 BA" 'mem_-u**er 5 N!LL% D7O/D siLe_in_-ytes 5 =% -#uccess 5 FreeImage_AcUuire)emory(dst_memory0 Imem_-u**er0 IsiLe_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 siLeo*(BA" $0 siLe_in_-ytes0 stream$% *close(stream$% 9 ++ close and *ree t&e memory stream FreeImage_Close)emory(dst_memory$% 9 9 return "/! %
return FAL# %
The following sample shows how "o modify an inpu" memory s"ream and sa#e your modifica"ions in"o an ou"pu" memory s"ream! Do"e "ha" "he inpu" s"ream is lef" unchanged1 all modifica"ions are s"ored in"o a cacheM "his cache is "hen used "o apply your modifica"ion on sa#ing!
(ppendi) 63
static BOOL loadBu**er(const c&ar 'lpsLPat&Name0 BA" struct stat *ile_in*o% int result%
''-u**er0 D7O/D 'lengt&$ 1
++ get data associated ;it& lpsLPat&Name result 5 stat(lpsLPat&Name0 I*ile_in*o$% i*(result 55 =$ 1 ++ allocate a memory -u**er and load temporary data '-u**er 5 (BA" '$malloc(*ile_in*oGst_siLe ' siLeo*(BA" $$% i*('-u**er$ 1 FIL 'stream 5 *open(lpsLPat&Name0 2r-2$% i*(stream$ 1 'lengt& 5 (D7O/D$*read('-u**er0 siLeo*(BA" $0 *ile_in*oGst_siLe0 stream$% *close(stream$% 9 return "/! %
9 9
return FAL# %
BOOL test)emory#tream)ultiPageOpen#ave(const c&ar 'lpsLPat&Name0 c&ar 'output0 int input_*lag0 int output_*lag$ 1 BOOL -#uccess 5 FAL# % BA" '-u**er 5 N!LL% D7O/D -u**er_siLe 5 =% ++ load source stream as a -u**er0 iGeG ++ allocate a memory -u**er and load temporary data -#uccess 5 loadBu**er(lpsLPat&Name0 I-u**er0 I-u**er_siLe$% assert(-#uccess$% ++ attac& t&e -inary data to a memory stream FI) )O/A 'src_stream 5 FreeImage_Open)emory(-u**er0 -u**er_siLe$% 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_stream0 input_*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<Page(src0 ?$% i*(di-$ 1 FreeImage_Invert(di-$% ++ !nload t&e -itmap (apply c&ange to src0 modi*ications are stored to t&e cac&e$ FreeImage_!nloc<Page(src0 di-0 "/! $% 9 ++ delete page = (modi*ications are stored to t&e cac&e$ FreeImage_DeletePage(src0 =$% ++ insert a ne; page at position Y=Y (modi*ications are stored to t&e cac&e$ FIBI")AP 'page 5 create]onePlateImage(EC?0 EC?0 C?B$% FreeImage_InsertPage(src0 =0 page$% FreeImage_!nload(page$%
++ save t&e modi*ication into t&e output stream GGG i*(src$ 1 ++ open and allocate a memory stream FI) )O/A 'dst_stream 5 FreeImage_Open)emory($% assert(dst_stream$%
65 (ppendi)
++ 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 BA" 'dst_-u**er 5 N!LL% D7O/D siLe_in_-ytes 5 =% FreeImage_AcUuire)emory(dst_stream0 Idst_-u**er0 IsiLe_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 siLeo*(BA" $0 siLe_in_-ytes0 stream$% *close(stream$% 9 ++ close and *ree t&e memory stream FreeImage_Close)emory(dst_stream$% 9 return "/! %
i*(-u**er$ 1 *ree(-u**er$% 9 9 return FAL# %
(ppendi) 65
Compression functions
FreeImage uses many Open Source "hird par"y libraries in order "o load or sa#e complex image file forma"s! (mong "hese libraries, some of "hem, such as "he KLib library, deal wi"h compression 8 decompression of memory buffers! Since "his fea"ure may be useful in many applica"ions and no" only for image compression, FreeImage pro#ides an in"erface "o "he main func"ionali"ies of "hese libraries! 3urren"ly, only KLib compression is suppor"ed! O"her compression algori"hms may be added wi"h fu"ure releases of FreeImage!
FreeImage-;LibCompress
DLL_API D7O/D DLL_CALLCONV FreeImage_]Li-Compress(BA" BA" 'source0 D7O/D source_siLe$% 'target0 D7O/D target_siLe0
3ompresses a source buffer in"o a "arge" buffer, using "he KLib library! 7pon en"ry, "arge"6siLe is "he "o"al siLe of "he des"ina"ion buffer, which mus" be a" leas" ,!$W larger "han source6siLe plus $+ by"es! The func"ion re"urns "he ac"ual siLe of "he compressed buffer, or re"urns , if an error occurred!
BA" 'data 5 N!LL% D7O/D original_siLe 5 =% ++ GGG data 5 (BA" '$malloc(original_siLe ' siLeo*(BA" $$% ++ GGG ++ compress data D7O/D compressed_siLe 5 (D7O/D$((dou-le$ original_siLe O (=GC ' (dou-le$ original_siLe$ O C?$% BA" 'compressed_data 5 (BA" '$malloc(compressed_siLe ' siLeo*(BA" $$% compressed_siLe 5 FreeImage_]Li-Compress(compressed_data0 compressed_siLe0 data0 original_siLe$% ++ ;rite data to dis< *;rite(Ioriginal_siLe0 siLeo*(D7O/D$0 C0 stream$% *;rite(Icompressed_siLe0 siLeo*(D7O/D$0 C0 stream$% *;rite(compressed_data0 siLeo*(BA" $0 compressed_siLe0 stream$% *ree(compressed_data$%
FreeImage-;Lib9ncompress
DLL_API D7O/D DLL_CALLCONV FreeImage_]Li-!ncompress(BA" BA" 'source0 D7O/D source_siLe$% 'target0 D7O/D target_siLe0
0ecompresses a source buffer in"o a "arge" buffer, using "he KLib library! 7pon en"ry, "arge"6siLe is "he "o"al siLe of "he des"ina"ion buffer, which mus" be large enough "o hold "he en"ire uncompressed da"a! The siLe of "he uncompressed da"a mus" ha#e been sa#ed pre#iously by "he compressor and "ransmi""ed "o "he decompressor by some mechanism ou"side "he scope of "his compression library! The func"ion re"urns "he ac"ual siLe of "he uncompressed buffer, or re"urns , if an error occurred!
66 (ppendi)
BA" 'data 5 N!LL% D7O/D original_siLe 5 =0 compressed_siLe 5 =% ++ GGG ++ read data *rom dis< *read(Ioriginal_siLe0 siLeo*(D7O/D$0 C0 stream$% *read(Icompressed_siLe0 siLeo*(D7O/D$0 C0 stream$% data 5 (BA" '$malloc(original_siLe ' siLeo*(BA" $$% compressed_data 5 (BA" '$malloc(compressed_siLe ' siLeo*(BA" $$% *read(compressed_data0 siLeo*(BA" $0 compressed_siLe0 stream$% ++ decompress data D7O/D siLe 5 =% siLe 5 FreeImage_]Li-!ncompress(data0 original_siLe0 compressed_data0 compressed_siLe$% assert(siLe 55 original_siLe$% *ree(compressed_data$%
FreeImage-;Lib.;ip
DLL_API D7O/D DLL_CALLCONV FreeImage_]Li-(]ip(BA" 'source0 D7O/D source_siLe$% 'target0 D7O/D target_siLe0 BA"
3ompresses a source buffer in"o a "arge" buffer, using "he KLib library! 7pon en"ry, "arge"6siLe is "he "o"al siLe of "he des"ina"ion buffer, which mus" be a" leas" ,!$W larger "han source6siLe plus +; by"es! On success, "he "arge" buffer con"ains a EKI- compa"ible layou"!
BA" 'data 5 N!LL% D7O/D original_siLe 5 =% ++ GGG data 5 (BA" '$malloc(original_siLe ' siLeo*(BA" $$% ++ GGG ++ initial siLe is original plus over&ead I gLipT&eader D7O/D compressed_siLe 5 (D7O/D$((dou-le$ original_siLe O (=GC ' (dou-le$ original_siLe$ O ?@$% BA" 'compressed_data 5 (BA" '$malloc(compressed_siLe ' siLeo*(BA" $$%
compressed_siLe 5 FreeImage_]Li-(]ip(compressed_data0 compressed_siLe0 data0 original_siLe$% ++ no; compressed_data contains Ycompressed_siLeY -ytes o* (]IP compressed data ++ ;rite data to a stream ++ GGG *ree(compressed_data$%
This func"ion is useful in con&unc"ion wi"h "he memory:i8o func"ions, if one is using "his "o compress some"hing "o send i" gLip:compressed o#er "he in"erne" )where a simple Lip:layou" will no" be accep"ed*! 3us"om or more complex layou"s may be ob"ained using a 3@3>+ builder in con&uc"ion wi"h "he exis"ing Lip compression func"ion )see "he FreeImage6KLib3@3>+ func"ion*!
FreeImage-;LibC+C3'
DLL_API D7O/D DLL_CALLCONV FreeImage_]Li-C/C>?(D7O/D crc0 BA" source_siLe$% 'source0 D7O/D
7pda"es a running crc from source )whose siLe in by"es is gi#en source_si"e* and re"urns "he upda"ed crc, using "he KLib library! If source is D7LL, "his func"ion re"urns "he reCuired ini"ial #alue for "he crc! O"herwise, i" re"urns "he new crc #alue!
(ppendi) 6"
FreeImage-;lib.9n@ip
DLL_API D7O/D DLL_CALLCONV FreeImage_]Li-(!nLip(BA" 'source0 D7O/D source_siLe$% 'target0 D7O/D target_siLe0 BA"
0ecompresses a gLipped source buffer in"o a "arge" buffer, using "he KLib library! 7pon en"ry, "arge"6siLe is "he "o"al siLe of "he des"ina"ion buffer, which mus" be large enough "o hold "he en"ire uncompressed da"a! The siLe of "he uncompressed da"a mus" ha#e been sa#ed pre#iously by "he compressor and "ransmi""ed "o "he decompressor by some mechanism ou"side "he scope of "his compression library! The func"ion re"urns "he ac"ual siLe of "he uncompressed buffer or re"urns , if an error occurred!
6& (ppendi)
<elper functions
FreeImage-IsLittle,ndian
DLL_API BOOL DLL_CALLCONV FreeImage_IsLittle ndian($%
This func"ion re"urns T@72 if "he pla"form running FreeImage uses "he Li""le 2ndian con#en"ion )In"el processors* and re"urns F(LS2 if i" uses "he %ig 2ndian con#en"ion )Mo"orola processors*!
FreeImage-Loo%upF11Color
DLL_API BOOL DLL_CALLCONV FreeImage_Loo<upRCCColor(const c&ar 'sLColor0 BA" BA" 'n(reen0 BA" 'nBlue$% 'n/ed0
3on#er"s a $$ color name in"o a corresponding @E% #alue! 7pon en"ry, sL3olor is "he color name! On ou"pu", n@ed, nEreen and n%lue are "he color componen"s in "he range U,!!+PPV! The func"ion re"urns T@72 if successful, F(LS2 o"herwise!
BA" red0 green0 -lue% BOOL -/esult% -/esult 5 FreeImage_Loo<upRCCColor(2papaya ;&ip20 Ired0 Igreen0 I-lue$% i*(-/esult$ 1 assert((red 55 ?EE$ II (green 55 ?>^$ II (-lue 55 ?C>$$% 9
FreeImage-Loo%up0C.Color
DLL_API BOOL DLL_CALLCONV FreeImage_Loo<up#V(Color(const c&ar 'sLColor0 BA" BA" 'n(reen0 BA" 'nBlue$% 'n/ed0
3on#er"s a S4E color name in"o a corresponding @E% #alue! 7pon en"ry, sL3olor is "he color name! On ou"pu", n@ed, nEreen and n%lue are "he color componen"s in "he range U,!!+PPV! The func"ion re"urns T@72 if successful, F(LS2 o"herwise!
BA" red0 green0 -lue% BOOL -/esult% -/esult 5 FreeImage_Loo<up#V(Color(2lemonc&i**on20 Ired0 Igreen0 I-lue$% i*(-/esult$ 1 assert((red 55 ?EE$ II (green 55 ?E=$ II (-lue 55 ?=E$$% 9
+eference Scalable 4ec"or Eraphics )S4E* $!$ Specifica"ion! UOnlineV h""p188www!w>!org8T@8S4E8"ypes!h"ml
(ppendi) 6=
!etadata function reference
Introduction
Me"ada"a or 5da"a abou" da"a5 describe "he con"en", Cuali"y, condi"ion, and o"her charac"eris"ics of da"a such as images! In FreeImage, me"ada"a is informa"ion a""ached "o an image in "he form of keywords, free "ex" or o"her da"a "ypes! This informa"ion can be rela"i#ely s"raigh"forward such as au"hor, da"e of crea"ion or sub&ec" con"en" of a resource! I" can also be more complex and less easily defined )e!g! pic"ure "aking condi"ions, E-S informa"ion for recording posi"ion informa"ion, e"c!*! Me"ada"a s"oring and re"rie#al usually conform "o a s"andard or a specifica"ion! 2xamples of me"ada"a s"andards used "o describe images include I-T38D((, 2 IF, EeoTIFF or (dobe M-! S"andards are no" always used howe#er! Many image forma"s use "heir own proprie"ary way "o s"ore me"ada"a, ei"her as simple "ex" s"rings or in a more complex way )e!g! <%IM markers used by (dobe -ho"oshop*! (l"hough many s"andards or proprie"ary forma"s are used "o describe images wi"h me"ada"a, FreeImage pro#ides you wi"h a simple in"erface "o deal wi"h all informa"ion a""ached "o your images!
FreeImage $ag
FreeImage uses a s"ruc"ure known as a tag "o s"ore me"ada"a informa"ion! The no"ion of "ag origina"es from "he TIFF specifica"ion and because of i"s uni#ersali"y, i" is widely used "o s"ore me"ada"a informa"ion in a file! FreeImage pro#ides an enhanced #ersion of "he s"andard TIFF or 2xif "ag s"ruc"ure! This #ersion is described below1 Field name
%ey description id type count length value
Data type
-oin"er "o a 3 s"ring )char A* -oin"er "o a 3 s"ring )char A* WO@0 )unsigned $=:bi"* WO@0 )unsigned $=:bi"* 0WO@0 )unsigned >+:bi"* 0WO@0 )unsigned >+:bi"* -oin"er "o a >+:bi" #alue )#oid A*
Description
Tag field name )uniCue inside a me"ada"a model* Tag descrip"ion if a#ailable, D7LL o"herwise Tag I0 if a#ailable, , o"herwise Tag da"a "ype ) see F@226IM(E26M0TB-2 below* Dumber of type componen"s in "he "ag Leng"h of "he "ag #alue in by"es Tag #alue
$able 11* FreeImage FI$(. structure. Ei#en a me"ada"a model )e!g! 2xif, 2xif E-S, I-T38D((*, "he "ag key )or "ag field name* is uniCue inside "his da"a model! This uniCueness allows FreeImage "o use "his key "o index "he "ag inside a hash "able, in order "o speed up "ag access! Whene#er you s"ore a "ag inside a me"ada"a model, you "hus need "o pro#ide a uniCue key wi"h "he "ag "o s"ore!
"# (ppendi)
( FreeImage "ag may be used "o s"ore any kind of da"a )e!g! s"rings, in"egers, doubles, ra"ional numbers, e"c!*! The comple"e lis" of da"a "ype suppor"ed by FreeImage is gi#en in Table $+! For example, when "he "ag da"a "ype indica"es a double and "he "ag coun" is <, "hen "he "ag #alue is an array of < doubles! I"s leng"h should be =; by"es )< x siLeof)double**! If "he "ag da"a "ype indica"es a ra"ional and "he leng"h is ;< by"es, "hen "here are );< by"es 8 )+ x ;: by"es** S = ra"ional #alues in "he "ag! (s for (S3II s"rings, "he #alue of "he coun" par" of an (S3II "ag en"ry includes "he D7LL!
$ag data type

, S FI0T6DOTB-2 $ S FI0T6%BT2 + S FI0T6(S3II > S FI0T6S.O@T ; S FI0T6LODE P S FI0T6@(TIOD(L = S FI0T6S%BT2 T S FI0T67D02FID20 < S FI0T6SS.O@T ? S FI0T6SLODE $, S FI0T6S@(TIOD(L $$ S FI0T6FLO(T $+ S FI0T60O7%L2 $> S FI0T6IF0 $; S FI0T6-(L2TT2
Description
-laceholder )do no" use "his "ype* <:bi" unsigned in"eger <:bi" by"e "ha" con"ains a T:bi" (S3II codeM "he las" by"e mus" be D7L )binary Lero* $=:bi" )+:by"e* unsigned in"eger >+:bi" );:by"e* unsigned in"eger Two LODEs1 "he firs" represen"s "he numera"or of a frac"ionM "he second, "he denomina"or (n <:bi" signed )"wos:complemen"* in"eger (n <:bi" by"e "ha" may con"ain any"hing, depending on "he defini"ion of "he field! ( $=:bi" )+:by"e* signed )"wos:complemen"* in"eger ( >+:bi" );:by"e* signed )"wos:complemen"* in"eger Two SLODE's1 "he firs" represen"s "he numera"or of a frac"ion, "he second "he denomina"or Single precision );:by"e* I222 forma" 0ouble precision )<:by"e* I222 forma" FI0T6IF0 da"a "ype is iden"ical "o LODE, bu" is only used "o s"ore offse"s >+:bi" );:by"e* @E%X7(0
$able 1'* FreeImage tag data types 1F+,,-I!(.,-!D$34, identifier2.
FreeImage metadata model

The me"ada"a models curren"ly recogniLed by "he library are lis"ed in Table $>, "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 FreeImage me"ada"a models*!
(ppendi) "1
!etadata model G FIF

# I FI!D-C/!!,:$0 1 I FI!D-,FIF-!(I: ' I FI!D-,FIF-,FIF 3 I FI!D-,FIF-.40 5 I FI!D-,FIF-!(J,+:/$, 5 I FI!D-,FIF-I:$,+/4 6 I FI!D-I4$C " I FI!D-F!4 & I FI!D-.,/$IFF = I FI!D-(:I!($I/: 1# I FI!D-C90$/! 11 I FI!D-,FIF-+(E
FIF-?4,. FIF-$IFF FIF-4:. FIF-.IF FIF-+(E

@8W @ @ @ @ @ @8W @8W : : : @8W : @ @ : : : @8W @8W @8W : : : @8W : : : : : : @8W : : : : @8W : : : : : : : : @8W : : : @ @ @ @ @ : : : : : :
+ S @ead, E S Wri"e, 7 S Do" implemen"ed
$able 13* !etadata models supported by FreeImage.
"' (ppendi)
$ag creation and destruction

FreeImage-Create$ag
DLL_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 "o FreeImage60ele"eTag when no longer in use! Tag crea"ion and des"ruc"ion func"ions are only needed when you use "he FreeImage6Se"Me"ada"a func"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 "o FreeImage60ele"eTag when no longer in use!
(ppendi) "3
$ag accessors
FreeImage-.et$agJey
DLL_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"AP 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 type uni"s*! For example, when "he "ag da"a "ype indica"es a double )i!e! a FI0T60O7%L2 "ype* and "he "ag coun" is <, "hen "he "ag #alue is an array of < doubles!
FreeImage-.et$agLength
DLL_API D7O/D DLL_CALLCONV FreeImage_(et"agLengt&(FI"A( 'tag$%
@e"urns "he leng"h of "he "ag #alue in by"es!
FreeImage-.et$agCalue
DLL_API const void 'DLL_CALLCONV FreeImage_(et"agValue(FI"A( 'tag$%
@e"urns "he "ag #alue! It is up to you to interpret the returned pointer correctly, according to the results of FreeImage-.et$ag$ype and FreeImage-.et$agCount.
"5 (ppendi)
FreeImage-0et$agJey
DLL_API BOOL DLL_CALLCONV FreeImage_#et"ag6ey(FI"A( 'tag0 const c&ar '<ey$%
Se" "he "ag field name )al>ays reHuired, mus" be uniCue inside a me"ada"a model*! The func"ion re"urns T@72 if successful and re"urns F(LS2 o"herwise!
FreeImage-0et$agDescription
DLL_API BOOL DLL_CALLCONV FreeImage_#et"agDescription(FI"A( 'tag0 const c&ar 'description$%
Se" "he )usually op"ional* "ag descrip"ion! The func"ion re"urns T@72 if successful and re"urns F(LS2 o"herwise! The "ag descrip"ion is ne#er s"ored in a file! FreeImage main"ains an in"ernal "able for all known "ags, "oge"her wi"h "heir descrip"ion when a#ailable! Whene#er you read a known "ag, "he library is able "o gi#e "he "ag descrip"ion )pro#ided "ha" "he "ag is known by "he library* using FreeImage6Ee"Tag0escrip"ion! .owe#er, you will ne#er ha#e "o pro#ide a "ag descrip"ion when s"oring a "ag!
FreeImage-0et$agID
DLL_API BOOL DLL_CALLCONV FreeImage_#et"agID(FI"A( 'tag0 7O/D id$%
Se" "he )usually op"ional* "ad I0! The func"ion re"urns T@72 if successful and re"urns F(LS2 o"herwise!
FreeImage-0et$ag$ype
DLL_API BOOL DLL_CALLCONV FreeImage_#et"ag"ype(FI"A( 'tag0 F/ _I)A( _)D"AP type$%
Se" "he "ag da"a "ype )al>ays reHuired, see Table $+ for a lis" of a#ailable da"a "ypes*! The func"ion re"urns T@72 if successful and re"urns F(LS2 o"herwise!
FreeImage-0et$agCount
DLL_API BOOL DLL_CALLCONV FreeImage_#et"agCount(FI"A( 'tag0 D7O/D count$%
Se" "he number of da"a in "he "ag ) al>ays reHuired, expressed in tag type uni"*! The func"ion re"urns T@72 if successful and re"urns F(LS2 o"herwise!
FreeImage-0et$agLength
DLL_API BOOL DLL_CALLCONV FreeImage_#et"agLengt&(FI"A( 'tag0 D7O/D lengt&$%
Se" "he leng"h of "he "ag #alue, in by"es ) al>ays reHuired*! The func"ion re"urns T@72 if successful and re"urns F(LS2 o"herwise!
(ppendi) "5
FreeImage-0et$agCalue
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"urns F(LS2 o"herwise!
This func"ion mus" be called after "he "ag da"a "ype, "ag coun" and "ag leng"h ha#e been filled! O"herwise, you will be unable "o successfully call FreeImage6Se"Me"ada"a!
"6 (ppendi)
!etadata iterator
FreeImage-FindFirst!etadata
DLL_API FI) "ADA"A 'DLL_CALLCONV FreeImage_FindFirst)etadata(F/ FIBI")AP 'di-0 FI"A( ''tag$% _I)A( _)D)OD L model0
-ro#ides informa"ion abou" "he firs" ins"ance of a "ag "ha" ma"ches "he me"ada"a model specified in "he model argumen"! If successful, FreeImage6FindFirs"Me"ada"a re"urns a uniCue search handle iden"ifying "he group of "ags ma"ching "he model specifica"ion, which can be used in a subseCuen" call "o FreeImage6FindDex"Me"ada"a or "o FreeImage6Find3loseMe"ada"a! When "he me"ada"a model does no" exis" in "he inpu" dib, FreeImage6FindFirs"Me"ada"a re"urns D7LL!
FreeImage-Find:e)t!etadata
DLL_API BOOL DLL_CALLCONV FreeImage_FindNeVt)etadata(FI) "ADA"A 'md&andle0 FI"A( ''tag$%
Find "he nex" "ag, if any, "ha" ma"ches "he me"ada"a model argumen" in a pre#ious call "o FreeImage6FindFirs"Me"ada"a, and "hen al"ers "he "ag ob&ec" con"en"s accordingly! If successful, FreeImage6FindDex"Me"ada"a re"urns T@72! O"herwise, i" re"urns F(LS2, indica"ing "ha" no more ma"ching "ags could be found!
FreeImage-FindClose!etadata
DLL_API void DLL_CALLCONV FreeImage_FindClose)etadata(FI) "ADA"A 'md&andle$%
3loses "he specified me"ada"a search handle and releases associa"ed resources
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called Jdi-K FI"A( 'tag 5 N!LL% FI) "ADA"A 'md&andle 5 N!LL% md&andle 5 FreeImage_FindFirst)etadata(FI)D_ RIF_)AIN0 di-0 Itag$% i*(md&andle$ 1 do 1 ++ process t&e tag print*(F8s3nH0 FreeImage_(et"ag6ey(tag$$% ++ GGG 9 ;&ile(FreeImage_FindNeVt)etadata(md&andle0 Itag$$% 9 FreeImage_FindClose)etadata(md&andle$%
(ppendi) ""
!etadata accessors
FreeImage-.et!etadata
DLL_API BOOL DLL_CALLCONV FreeImage_(et)etadata(F/ 'di-0 const c&ar '<ey0 FI"A( ''tag$% _I)A( _)D)OD L model0 FIBI")AP
@e"rie#e a me"ada"a a""ached "o a dib! 7pon en"ry, model is "he me"ada"a model "o look for, di) is "he image "ha" con"ains me"ada"a, !ey is "he me"ada"a field name )uniCue inside a me"ada"a model* and tag is a FIT(E s"ruc"ure re"urned by "he func"ion! When "he searched "ag doesn'" exis", "he "ag ob&ec" is lef" unchanged and "he func"ion re"urns F(LS2! O"herwise, "he func"ion re"urns T@72 and "he "ag ob&ec" is popula"ed wi"h "he me"ada"a informa"ion!
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called Jdi-K ++ (et t&e camera model FI"A( 'tag)a<e 5 N!LL% FreeImage_(et)etadata(FI)D_ RIF_)AIN0 di-0 2)a<e20 Itag)a<e$% i*(tag)a<e 45 N!LL$ 1 ++ &ere ;e <no; (according to t&e Vi* speci*ications$ t&at tag)a<e is a C string print*(2Camera model X 8s3n20 (c&ar'$FreeImage_(et"agValue(tag)a<e$$% ++ i* ;e donKt &ave t&e speci*ications0 ;e can still convert t&e tag to a C string print*(2Camera model X 8s3n20 FreeImage_"ag"o#tring(FI)D_ RIF_)AIN0 tag)a<e$$% 9
When a "ag re"urned by FreeImage_Get,etadata or by "he me"ada"a i"era"or func"ions is modified, changes will be applied "o "he corresponding "ag a""ached "o "he bi"map! Sa#ing "he bi"map will "hus sa#e "he modified "ag )pro#ided "ha" "he library can sa#e "he corresponding me"ada"a model*!
FreeImage-0et!etadata
DLL_API BOOL DLL_CALLCONV FreeImage_#et)etadata(F/ 'di-0 const c&ar '<ey0 FI"A( 'tag$% _I)A( _)D)OD L model0 FIBI")AP
(""ach a new FreeImage "ag "o a dib! 7pon en"ry, model is "he me"ada"a model used "o s"ore "he "ag, di) is "he "arge" image, !ey is "he "ag field name and tag is "he FreeImage "ag "o be a""ached! If tag is :9LL then the metadata is deleted. If both %ey and tag are :9LL then the metadata model is deleted. The func"ion re"urns T@72 on success and re"urns F(LS2 o"herwise!
The "ag field name )or "ag key* used by FreeImage "o index a "ag is gi#en by "he
"& (ppendi)
me"ada"a model specifica"ion )e!g! 2 IF specifica"ion or (dobe M- specifica"ion*!
c&ar 'Vmp_pro*ile 5 N!LL% D7O/D pro*ile_siLe 5 =% ++ GGG ++ ++ ++ ++ t&e *ollo;ing assumes t&at you &ave a R)L pac<et stored in t&e (null terminated$ varia-le YVmp_pro*ileYG "&e siLe o* t&e pac<et is given -y Ypro*ile_siLeY and includes t&e N!LL value
++ create a tag FI"A( 'tag 5 FreeImage_Create"ag($% i*(tag$ 1 ++ *ill t&e tag mem-ers // note t%at t%e FI,D_X,P "o$el accept a single 1ey na"e$ 3X,LPac1et4 FreeImage_#et"ag6ey(tag0 FR)LPac<etH$% FreeImage_#et"agLengt&(tag0 pro*ile_siLe$% FreeImage_#et"agCount(tag0 pro*ile_siLe$% FreeImage_#et"ag"ype(tag0 FID"_A#CII$% // t%e tag alue "ust &e sto!e$ after // t%e tag $ata type) tag count an$ tag lengt% %a e &een fille$5 FreeImage_#et"agValue(tag0 Vmp_pro*ile$% ++ store t&e tag FreeImage_#et)etadata(FI)D_R)P0 di-0 FreeImage_(et"ag6ey(tag$0 tag$% ++ destroy t&e tag FreeImage_Delete"ag(tag$%
+'' Add a single IP"C tag to a FIBI")AP NBX "&e tag ID is not needed as it is *illed automatically -y FreeImage_#et)etadata ,param image Aour image to -e saved ,param <ey "ag <ey ,param value "ag value '+ void add_IP"C_tag(FIBI")AP 'image0 const c&ar '<ey0 const c&ar 'value$ 1 ++ create a tag FI"A( 'tag 5 FreeImage_Create"ag($% i*(tag$ 1 ++ *ill t&e tag FreeImage_#et"ag6ey(tag0 <ey$% FreeImage_#et"agLengt&(tag0 strlen(value$ O C$% FreeImage_#et"agCount(tag0 strlen(value$ O C$% FreeImage_#et"ag"ype(tag0 FID"_A#CII$% FreeImage_#et"agValue(tag0 value$% FreeImage_#et)etadata(FI)D_IP"C0 image0 FreeImage_(et"ag6ey(tag$0 tag$% ++ destroy t&e tag FreeImage_Delete"ag(tag$% 9 9 +'' Add some IP"C tags to a FIBI")AP '+ void add_IP"C_)etadata(FIBI")AP 'di-$ 1 ++ 444 IP"C data is ignored -y P&otos&op ;&en t&ere is a R)L pac<et in t&e di- 444 add_IP"C_tag(di-0 2O-[ectName20 2my title2$% add_IP"C_tag(di-0 2CaptionTA-stract20 2my caption2$% add_IP"C_tag(di-0 27riterT ditor20 2mysel*2$% add_IP"C_tag(di-0 2ByTline20 2my name2$% add_IP"C_tag(di-0 2ByTline"itle20 2my position2$% add_IP"C_tag(di-0 26ey;ords20 2FreeImage%Li-rary%Images%Compression2$% 9
(ppendi) "=
!etadata helper functions

FreeImage-.et!etadataCount
DLL_API unsigned DLL_CALLCONV FreeImage_(et)etadataCount(F/ FIBI")AP 'di-$% _I)A( _)D)OD L model0
@e"urns "he number of "ags con"ained in "he model me"ada"a model a""ached "o "he inpu" dib!
unsigned count% i*(count 5 FreeImage_(et)etadataCount(FI)D_ RIF_(P#0 di-$$ 1 ++ process (P# data 9
FreeImage-Clone!etadata
DLL_API BOOL DLL_CALLCONV FreeImage_Clone)etadata(FIBI")AP 'dst0 FIBI")AP 'src$%
3opy all me"ada"a con"ained in src in"o dst, wi"h "he excep"ion of FIM06(DIM(TIOD me"ada"a )"hese me"ada"a are no" copied because "his may cause problems when sa#ing "o EIF*! When a src me"ada"a model already exis"s in dst, "he dst me"ada"a model is firs" erased before copying "he src one! When a me"ada"a model already exis"s in dst and no" in src, i" is lef" un"ouched! .oriLon"al and #er"ical resolu"ion info )re"urned by FreeImage6Ee"0o"s-erMe"er FreeImage6Ee"0o"s-erMe"erB* is also copied from src "o dst! and by
The func"ion re"urns T@72 on success and re"urns F(LS2 o"herwise )e!g! when src or dst are in#alid*!
2#ery FreeImage func"ion wi"h a signa"ure such as FIBI")AP 'dst 5 FreeImage_Function(FIBI")AP 'src0 GGG$ will in"ernally clone src me"ada"a in"o ds"! Thus, you will ne#er ha#e "o use "his func"ion when using FreeImage func"ions! .owe#er, you may ha#e "o use "his func"ion when crea"ing your o n processing func"ions! The FreeImage63loneMe"ada"a func"ions clones me"ada"a from one image "o ano"her! (l"hough "he "arge" image con"ains all me"ada"a of "he source image, some me"ada"a canQ" be sa#ed "o disk, see e!g! "his pseudo:code1
FreeImage_Clone)etadata(dst_[peg0 src_[peg$% ++ dst_[peg &as t&e same metadata as src_[peg FreeImage_#ave(FIF_ZP (0 dst_[peg0 2eVampleG[pg20 =$% ne;_[peg 5 FreeImage_Load(FIF_ZP (0 2eVampleG[pg20 =$% ++ ne;_[peg is missing some metadata
FreeImage-$ag$o0tring
DLL_API const c&ar' DLL_CALLCONV FreeImage_"ag"o#tring(F/ 'tag0 c&ar ')a<e FI_D FA!L"(N!LL$$% _I)A( _)D)OD L model0 FI"A(
&# (ppendi)
3on#er"s a FreeImage "ag s"ruc"ure "o a s"ring "ha" represen"s "he in"erpre"ed "ag #alue! The "ag #alue is in"erpre"ed according "o "he me"ada"a model specifica"ion! For example, consider a "ag ex"rac"ed from "he FIM062 IF62 IF me"ada"a model, whose I0 is ,x?+,? and whose key is FFlashG! Then if "he "ag #alue is ,x,,,P, "he func"ion will re"urn FS"robe re"urn ligh" no" de"ec"edG! 7pon en"ry, model is "he me"ada"a model from which "he "ag was ex"rac"ed, tag is "he FreeImage "ag "o in"erpre" and ,a!e is "he camera model! This las" parame"er is curren"ly no" used by "he library bu" will be used in "he fu"ure "o in"erpre" "he camera maker no"es )FIM062 IF6M(I2@DOT2 me"ada"a model*!
FreeImage_-ag-o$tring is no" "hread safe!
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called Ydi-Y FI"A( 'tag 5 N!LL% FI) "ADA"A 'md&andle 5 N!LL% md&andle 5 FreeImage_FindFirst)etadata(model0 di-0 Itag$% i*(md&andle$ 1 do 1 ++ convert t&e tag value to a &uman reada-le string const c%a! / alue = F!eeI"age_-ag-oSt!ing("o$el) tag*; ++ print t&e tag ++ note t&at most tags do not &ave a description0 ++ especially ;&en t&e metadata speci*ications are not availa-le i*(FreeImage_(et"agDescription(tag$$ 1 cout NN 2<ey X 2 NN FreeImage_(et"ag6ey(tag$ NN 2% value X 2 NN value NN 2% description X 2 NN FreeImage_(et"agDescription(tag$ NN 23n2% 9 else 1 cout NN 2<ey X 2 NN FreeImage_(et"ag6ey(tag$ NN 2% value X 2 NN value NN 2% description X (none$3n2% 9 9 9 ;&ile(FreeImage_FindNeVt)etadata(md&andle0 Itag$$%
FreeImage_FindClose)etadata(md&andle$%
(ppendi) &1
$ool%it function reference
+otation and flipping

FreeImage-+otate
$ < +; >+ $=7IDT$= ;<@E%$= =;@E%($= >+FLO(T ?=@E%F $+<@E%(F
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_/otate(FIBI")AP 'di-0 dou-le angle0 const void '-<color FI_D FA!L"(N!LL$$%
This func"ion ro"a"es a s"andard image )$:, <:bi" greyscale or a +;:, >+:bi" color*, a @E%)(*$= or @E%)(*F image by means of > shears! The angle of ro"a"ion is specified by "he angle parame"er in degrees! @o"a"ion occurs around "he cen"er of "he image area! @o"a"ed image re"ains siLe and aspec" ra"io of source image )des"ina"ion image siLe is usually bigger*, so "ha" "his func"ion should be used when ro"a"ing an image by ?,], $<,] or +T,]!
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called Jdi-K ++ per*orm a ^=` rotation (CC7 rotation$ FIBI")AP 'rotated 5 FreeImage_/otate(di-0 ^=$%
For 17bit images, ro"a"ion is limi"ed "o angles whose #alue is an in"eger mul"iple of ?,] )e!g! Y?,, ?,, $<,, +T,*! ( D7LL #alue is re"urned for o"her angles!
When "he angle #alue isn'" an in"eger mul"iple of ?,], "he background is filled wi"h "he supplied )!color parame"er! When )!color is D7LL )defaul" #alue*, "he background is filled wi"h a black color! The da"a "ype of )!color depends on "he image "ype )see "he following example*!
&' (ppendi)
FIBI")AP' test/otate7it&Bac<ground(FIBI")AP 'src0 dou-le angle$ 1 F/ _I)A( _"AP image_type 5 FreeImage_(etImage"ype(src$% s;itc&(image_type$ 1 case FI"_BI")APX s;itc&(FreeImage_(etBPP(src$$ 1 case BX 1 BA" color 5 C?B% return FreeImage_/otate(src0 angle0 Icolor$% 9 -rea<% case ?@X ++ ;e could also use Y/(B"/IPL colorY &ere case >?X 1 /(BM!AD color 5 1 =0 =0 ?EE0 = 9% ++ *or ?@T-it images0 t&e *irst > -ytes ;ill -e read ++ *or >?T-it images0 t&e *irst @ -ytes ;ill -e read return FreeImage_/otate(src0 angle0 Icolor$% 9 -rea<% 9 -rea<% case FI"_!IN"CDX 1 7O/D color 5 C?B% return FreeImage_/otate(src0 angle0 Icolor$% 9 -rea<% case FI"_/(BCDX ++ ;e could also use YFI/(BCD colorY &ere case FI"_/(BACDX 1 FI/(BACD color 5 1 =0 =0 ?EE0 = 9% ++ *or /(BCD images0 t&e *irst > 7O/D ;ill -e read ++ *or /(BACD images0 t&e *irst @ 7O/D ;ill -e read return FreeImage_/otate(src0 angle0 Icolor$% 9 -rea<% case FI"_FLOA"X 1 *loat color 5 =GEF% return FreeImage_/otate(src0 angle0 Icolor$% 9 -rea<% case FI"_/(BFX ++ ;e could also use YFI/(BF colorY &ere case FI"_/(BAFX 1 FI/(BAF color 5 1 =0 =0 C0 = 9% ++ *or /(BF images0 t&e *irst > *loat ;ill -e read ++ *or /(BAF images0 t&e *irst @ *loat ;ill -e read return FreeImage_/otate(src0 angle0 Icolor$% 9 -rea<%
9 9
return N!LL%
( demons"ra"ion of "his func"ion is gi#en in "he (ppendix )see 7sing "he ro"a"ion func"ions*!
+eferences -ae"h (!, ( Fas" (lgori"hm for Eeneral @as"er @o"a"ion! Eraphics Eems, p! $T?, (ndrew Elassner edi"or, (cademic -ress, $??,! Bari# 2!, .igh Cuali"y image ro"a"ion )ro"a"e by shear*! UOnlineV h""p188www!codepro&ec"!com8bi"map8ro"a"ebyshear!asp
(ppendi) &3
FreeImage-+otate,)
< +; >+
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_/otate V(FIBI")AP 'di-0 dou-le angle0 dou-le V_s&i*t0 dou-le y_s&i*t0 dou-le V_origin0 dou-le y_origin0 BOOL use_mas<$%
This func"ion performs a ro"a"ion and 8 or "ransla"ion of an <:bi" greyscale, +;: or >+:bi" image, using a >rd order )cubic* %:Spline! The ro"a"ed image will ha#e "he same wid"h and heigh" as "he source image, so "ha" "his func"ion is be""er sui"ed for compu"er #ision and robo"ics! The angle of ro"a"ion is specified by "he angle parame"er in degrees! .oriLon"al and #er"ical image "ransla"ions )in pixel uni"s* are specified by "he x6shif" and y6shif" parame"ers! @o"a"ion occurs around "he cen"er specified by x6origin and y6origin, also gi#en in pixel uni"s! When use6mask is se" "o T@72, "he irrele#an" par" of "he image is se" "o a black color, o"herwise, a mirroring "echniCue is used "o fill irrele#an" pixels!
++ t&is code assumes t&ere is a -itmap loaded and ++ present in a varia-le called Jdi-K ++ rotate t&e image a-out t&e center o* t&e image area dou-le V_orig 5 FreeImage_(et7idt&(di-$ + (dou-le$?% dou-le y_orig 5 FreeImage_(et.eig&t(di-$ + (dou-le$?% ++ per*orm a CE` CC7 rotation using a mas< (no translation$ FIBI")AP 'rotated 5 FreeImage_/otate V(di-0 CE0 =0 =0 V_orig0 y_orig0 "/! $%
( demons"ra"ion of "his func"ion is gi#en in "he (ppendix )see 7sing "he ro"a"ion func"ions*!
+eferences -hilippe Th/#enaL, Spline in"erpola"ion, a 3 source code implemen"a"ion! UOnlineV h""p188bigwww!epfl!ch8"he#enaL8 7nser M!, Splines1 ( -erfec" Fi" for Signal and Image -rocessing! I222 Signal -rocessing MagaLine, #ol! $=, no! =, pp! ++:><, Do#ember $???! 7nser M!, (ldroubi (!, 2den M!, %:Spline Signal -rocessing1 -ar" I::Theory! I222 Transac"ions on Signal -rocessing, #ol! ;$, no! +, pp! <+$:<>+, February $??>! 7nser M!, (ldroubi (!, 2den M!, %:Spline Signal -rocessing1 -ar" II::2fficien" 0esign and (pplica"ions! I222 Transac"ions on Signal -rocessing, #ol! ;$, no! +, pp! <>;:<;<, February $??>!
FreeImage-Flip<ori@ontal
DLL_API BOOL DLL_CALLCONV FreeImage_Flip.oriLontal(FIBI")AP 'di-$%
Flip "he inpu" dib horiLon"ally along "he #er"ical axis!
FreeImage-FlipCertical
DLL_API BOOL DLL_CALLCONV FreeImage_FlipVertical(FIBI")AP 'di-$%
Flip "he inpu" dib #er"ically along "he horiLon"al axis!
&5 (ppendi)
FreeImage-?4,.$ransform
DLL_API BOOL DLL_CALLCONV FreeImage_ZP ("rans*orm(const c&ar 'src_*ile0 const c&ar 'dst_*ile0 F/ _I)A( _ZP (_OP /A"ION operation0 BOOL per*ect FI_D FA!L"(FAL# $$%
-erforms a lossless ro"a"ion or flipping on a J-2E file! 7pon en"ry, src_file is "he source J-2E file and dst_file "he des"ina"ion J-2E file! 7sing "he same file for source and des"ina"ion is allowed1 "he source file will be "ransformed and o#erwri""en! The operation parame"er specifies "he kind of "ransforma"ion "o apply! The following "ransforma"ions are possible1 /peration
FIJ-2E6O-6DOD2 FIJ-2E6O-6FLI-6. FIJ-2E6O-6FLI-64 FIJ-2E6O-6T@(DS-OS2 FIJ-2E6O-6T@(DS42@S2 FIJ-2E6O-6@OT(T26?, FIJ-2E6O-6@OT(T26$<, FIJ-2E6O-6@OT(T26+T,
Description
Do "ransforma"ion )no"hing is done* .oriLon"al flip 4er"ical flip Transpose across upper:lef" "o lower:righ" axis Transpose across upper:righ" "o lower:lef" axis ?,:degree clockwise ro"a"ion $<,:degree ro"a"ion +T,:degree clockwise ro"a"ion )or ?,:degree ccw*
$able 15* F+,,-I!(.,-?4,.-/4,+($I/: constants. FreeImage6J-2ETransform works by rearranging "he compressed da"a )03T coefficien"s*, wi"hou" e#er fully decoding "he image! Therefore, i"s "ransforma"ions are lossless1 "here is no image degrada"ion a" all, which would no" be "rue if you used FreeImage_.oad followed by FreeImage_$a&e "o accomplish "he same con#ersion! The FIJ-2E6O-6T@(DS-OS2 "ransforma"ion has no res"ric"ions regarding image dimensions! The o"her "ransforma"ions opera"e ra"her oddly if "he image dimensions are no" a mul"iple of "he iM37 siLe )usually < or $= pixels*, because "hey can only "ransform comple"e blocks of 03T coefficien" da"a in "he desired way! The defaul" func"ion beha#ior when "ransforming an odd:siLe image is designed "o discard any un"ransformable edge pixels ra"her "han ha#ing a s"range:looking s"rip along "he righ" and8or bo""om edges of a "ransformed image! Ob#iously, when applied "o odd:siLe images, "he "ransforma"ion is no" re#ersible, so s"ric"ly speaking, "he opera"ion is no" lossless! In order "o a#oid lossy "ransforma"ion, you can se" "he perfect parame"er "o T@72! When using "his parame"er, any non re#ersible "ransform is a#oided, an error message is "hrown )"ha" you can log using FreeImage6Se"Ou"pu"Message* and "he func"ion will re"urn F(LS2!
FreeImage-?4,.$ransform9
DLL_API BOOL DLL_CALLCONV FreeImage_ZP ("rans*orm!(const ;c&ar_t 'src_*ile0 const ;c&ar_t 'dst_*ile0 F/ _I)A( _ZP (_OP /A"ION operation0 BOOL per*ect FI_D FA!L"(FAL# $$%
This func"ion works exac"ly like FreeImage6J-2ETransform 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"ion does no"hing and re"urns F(LS2!
(ppendi) &5
9psampling G do>nsampling
FreeImage-+escale
$ ; < $= +; >+ $=7IDT$= ;<@E%$= =;@E%($= >+FLO(T ?=@E%F $+<@E%(F
DLL_API FIBI")AP ' DLL_CALLCONV FreeImage_/escale(FIBI")AP 'di-0 int dst_;idt&0 int dst_&eig&t0 F/ _I)A( _FIL" / *ilter$%
This func"ion performs resampling )or scaling, Looming* of a greyscale or @E%)(* image "o "he desired des"ina"ion wid"h and heigh"! ( D7LL #alue is re"urned when "he bi"dep"h canno" be handled or when "here's no" enough memory )"his may happen wi"h #ery large images*! $=:bi" @E% bi"map are re"urned as +;:bi"! -ale""iLed and ;:bi" bi"map are re"urned as <:bi" pale""iLed images, using an in"ernal con#ersion "o +;:bi" followed by a color Cuan"iLa"ion, or are re"urned as >+:bi" if "hey con"ain "ransparency! @esampling refers "o changing "he pixel dimensions )and "herefore display siLe* of an image! When you downsample )or decrease "he number of pixels*, informa"ion is dele"ed from "he image! When you upsample )or increase "he number of pixels*, new pixels are added based on color #alues of exis"ing pixels! Bou specify an in"erpola"ion fil"er "o de"ermine how pixels are added or dele"ed! The following fil"ers can be used as resampling fil"ers1 Filter flag
FILT2@6%O FILT2@6%ILID2(@ FILT2@6%S-LID2 FILT2@6%I37%I3 FILT2@63(TM7LL@OM FILT2@6L(D3KOS>
Description
%ox, pulse, Fourier window, $s" order )cons"an"* %:Spline %ilinear fil"er ;"h order )cubic* %:Spline Mi"chell and De"ra#aliQs "wo:param cubic fil"er 3a"mull:@om spline, O#erhauser spline LancLos:windowed sinc fil"er
$able 15* I!(.,-FIL$,+ constants.
Some hin"s on how "o use "hese fil"ers are gi#en in "he (ppendix )see 3hoosing "he righ" resampling fil"er*!
+eferences -aul .eckber", 3 code "o Loom ras"er images up or down, wi"h nice fil"ering! 73 %erkeley, (ugus" $?<?! UOnlineV h""p188www:+!cs!cmu!edu8afs8cs!cmu!edu8Web8-eople8ph8heckber"!h"ml .ou .!S!, (ndrews .!3!, 3ubic Splines for Image In"erpola"ion and 0igi"al Fil"ering! I222 Trans! (cous"ics, Speech, and Signal -roc!, #ol! (SS-:+=, no! =, pp! P,<:P$T, 0ec! $?T<! Elassner (!S!, -rinciples of digi"al image syn"hesis! Morgan Iaufmann -ublishers, Inc, San Francisco, 4ol! +, $??P! Mi"chell 0on -!, De"ra#ali (run D!, @econs"ruc"ion fil"ers in compu"er graphics! In John 0ill, edi"or, 3ompu"er Eraphics )SIEE@(-. Q<< -roceedings*, 4ol! ++, Do! ;, pp! ++$:++<, (ugus" $?<<!
&6 (ppendi)
Ieys @!E!, 3ubic 3on#olu"ion In"erpola"ion for 0igi"al Image -rocessing! I222 Trans! (cous"ics, Speech, and Signal -rocessing, #ol! +?, no! =, pp! $$P>:$$=,, 0ec! $?<$!
FreeImage-!a%e$humbnail
$ ; < $= +; >+ $=7IDT$= ;<@E%$= =;@E%($= >+FLO(T ?=@E%F $+<@E%(F
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_)a<e"&um-nail(FIBI")AP 'di-0 int maV_piVel_siLe0 BOOL convert FI_D FA!L"("/! $$%
3rea"es a "humbnail from a greyscale or @E%)(* image so "ha" "he ou"pu" image fi"s inside a sCuare of siLe max_pixel_si"e, keeping aspec" ra"io! 0ownsampling is done using a bilinear fil"er )see FreeImage6@escale*! $=:bi" @E% bi"map are re"urned as +;:bi"! -ale""iLed and ;:bi" bi"map are re"urned as <:bi" or as >+:bi" if "hey con"ain "ransparency! When "he con&ert parame"er is se" "o T@72, .igh 0ynamic @ange images )FIT67IDT$=, FIT6@E%$=, FIT6@E%($=, FIT6FLO(T* are "ransparen"ly con#er"ed "o s"andard images )i!e! <:, +; or >+:bi" images*, using one of "he FreeImage63on#er"To con#ersion func"ion! (s for @%EU(VF images, "hey are con#er"ed "o +;:bi" using "he FreeImage6Tmo0rago,> func"ion wi"h defaul" op"ions!
(ppendi) &"
Sde*ine ".!)BNAIL_#I]
^= ++ *it inside a sUuare ;&ose siLe is ^= piVels
FIBI")AP ' ma<e"&um-nail(const c&ar 'sLPat&Name$ 1 FIBI")AP 'di- 5 N!LL% int *lags 5 =% ++ de*ault load *lag int original7idt& 5 =% ++ original image ;idt& int original.eig&t 5 =% ++ original image &eig&t F/ _I)A( _FO/)A" *i* 5 FreeImage_(etFile"ype(sLPat&Name$% i*(*i* 55 FIF_!N6NO7N$ return N!LL% i*(*i* 55 FIF_ZP ($ 1 FI"A( 'tag 5 N!LL% // fo! 6PE7 i"ages) +e can spee$up t%e loa$ing pa!t // using Li&6PE7 $o+nsa"pling featu!e +%ile loa$ing t%e i"age555 *lags _5 ".!)BNAIL_#I] NN CD% ++ load t&e didi- 5 FreeImage_Load(*i*0 sLPat&Name0 *lags$% i*(4di-$ return N!LL% ++ t&e di- may &ave -een do;nscaled -y ?V0 @V or BV ++ retrieve t&e original ;idt& I &eig&t (stored as comments *or t&is special case$ i*(FreeImage_(et)etadata(FI)D_CO)) N"#0 di-0 2OriginalZP (7idt&20 Itag$$ 1 original7idt& 5 atoi( (c&ar'$FreeImage_(et"agValue(tag$ $% 9 else 1 original7idt& 5 FreeImage_(et7idt&(di-$% 9 i*(FreeImage_(et)etadata(FI)D_CO)) N"#0 di-0 2OriginalZP (.eig&t20 Itag$$ 1 original.eig&t 5 atoi( (c&ar'$FreeImage_(et"agValue(tag$ $% 9 else 1 original.eig&t 5 FreeImage_(et.eig&t(di-$% 9 9 else 1 ++ any cases ot&er t&an t&e ZP ( caseX load t&e di- GGG i*(*i* 55 FIF_/A7$ 1 // 555 except fo! 8A9 i"ages) t!y to loa$ t%e e"&e$$e$ 6PE7 p!e ie+ // o! $efault to 87. :;<&it 555 *lag 5 /A7_P/ VI 7% 9 di- 5 FreeImage_Load(*i*0 sLPat&Name0 *lags$% i*(4di-$ return N!LL% original7idt& 5 FreeImage_(et7idt&(di-$% original.eig&t 5 FreeImage_(et.eig&t(di-$%
++ store Joriginal7idt&K and Joriginal.eig&tK *or later use : ++ store any ot&er metadata (suc& as Vi*$ *or later use : ++ GGG ++ create t&e reUuested t&um-nail FIBI")AP 't&um-nail 5 FreeImage_)a<e"&um-nail(di-0 ".!)BNAIL_#I] 0 "/! $% FreeImage_!nload(di-$% return t&um-nail%
&& (ppendi)
Color manipulation
FreeImage uses "he @E%)(* color model "o represen" color images in memory! ( <:bi" greyscale image has a single channel, of"en called "he black channel! ( +;:bi" image is made up of "hree <:bi" channels1 one for each of "he red, green and blue colors! For >+:bi" images, a four"h <:bi" channel, called alpha channel, is used "o crea"e and s"ore masks, which le" you manipula"e, isola"e, and pro"ec" specific par"s of an image! 7nlike "he o"hers channels, "he alpha channel doesn'" con#ey color informa"ion, in a physical sense! 3olor manipula"ion func"ions used in FreeImage allow you "o modify "he his"ogram of a specific channel! This "ransforma"ion is known as a point operation, and may be used "o ad&us" brigh"ness, con"ras" or gamma of an image, "o perform image enhancemen" )e!g! his"ogram eCualiLa"ion, non:linear con"ras" ad&us"men"* or e#en "o in#er" or "hreshold an image! 3urren"ly, "he following channels are defined in FreeImage1 Channel flag
FI336@E% FI336@20 FI336E@22D FI336%L72 FI336(L-.( FI336%L(3I FI336@2(L FI336IM(E FI336M(E FI336-.(S2
Description
Func"ion applies "o red, green and blue channels Func"ion applies "o red channel only Func"ion applies "o green channel only Func"ion applies "o blue channel only Func"ion applies "o alpha channel only Func"ion applies "o black channel 3omplex images1 func"ion applies "o "he real par" 3omplex images1 func"ion applies "o "he imaginary par" 3omplex images1 func"ion applies "o "he magni"ude 3omplex images1 func"ion applies "o "he phase
$able 16* F+,,-I!(.,-C/L/+-C<(::,L constants.
FreeImage-(dKustCurve
< +; >+
'L!"0 DLL_API BOOL DLL_CALLCONV FreeImage_Ad[ustCurve(FIBI")AP 'di-0 BA" F/ _I)A( _COLO/_C.ANN L c&annel$%
-erfoms an his"ogram "ransforma"ion on a <:, +;: or >+:bi" image according "o "he #alues of a lookup "able )L7T*! The "ransforma"ion changes one or more channels according "o "he following eCua"ion1 c'annel(x/ y) 0 .U-1c'annel(x/ y)2 The siLe of QL7TQ is assumed "o be +P=! The color channel "o be "ransformed is specified by "he c'annel parame"er! The "ransforma"ion is done as follows1

<:bi" images1 if "he image has a color pale""e, "he L7T is applied "o "his pale""e, o"herwise, i" is applied "o "he grey #alues! The channel parame"er is no" used! +;:bi" [ >+:bi" images1 if channel is eCual "o FI336@E%, "he same L7T is applied "o each color plane )@, E, and %*! O"herwise, "he L7T is applied "o "he specified channel only )@, E, % or (*!
The func"ion re"urns T@72 on success, F(LS2 o"herwise )e!g! when "he bi"dep"h of "he source dib canno" be handled*!
(ppendi) &=
FreeImage-(dKust.amma
< +; >+
DLL_API BOOL DLL_CALLCONV FreeImage_Ad[ust(amma(FIBI")AP 'di-0 dou-le gamma$%
-erforms gamma correc"ion on a <:, +;: or >+:bi" image! The gamma parame"er represen"s "he gamma #alue "o use )gamma O ,*! ( #alue of $!, lea#es "he image alone, less "han one darkens i", and grea"er "han one ligh"ens i"! The func"ion re"urns T@72 on success! I" re"urns F(LS2 when gamma is less "han or eCual "o Lero or when "he bi"dep"h of "he source dib canno" be handled!
FreeImage-(dKust rightness
< +; >+
DLL_API BOOL DLL_CALLCONV FreeImage_Ad[ustBrig&tness(FIBI")AP 'di-0 dou-le percentage$%
(d&us"s "he brigh"ness of a <:, +;: or >+:bi" image by a cer"ain amoun"! This amoun" is gi#en by "he percen"age parame"er, where percen"age is a #alue be"ween U:$,,!!$,,V! ( #alue , means no change, less "han , will make "he image darker and grea"er "han , will make "he image brigh"er! The func"ion re"urns T@72 on success, F(LS2 o"herwise )e!g! when "he bi"dep"h of "he source dib canno" be handled*!
FreeImage-(dKustContrast
< +; >+
DLL_API BOOL DLL_CALLCONV FreeImage_Ad[ustContrast(FIBI")AP 'di-0 dou-le percentage$%
(d&us"s "he con"ras" of a <:, +;: or >+:bi" image by a cer"ain amoun"! This amoun" is gi#en by "he percen"age parame"er, where percen"age is a #alue be"ween U:$,,!!$,,V! ( #alue , means no change, less "han , will decrease "he con"ras" and grea"er "han , will increase "he con"ras" of "he image! The func"ion re"urns T@72 on success, F(LS2 o"herwise )e!g! when "he bi"dep"h of "he source dib canno" be handled*!
FreeImage-Invert
$ ; < +; >+ $=7IDT$= ;<@E%$= =;@E%($=
DLL_API BOOL DLL_CALLCONV FreeImage_Invert(FIBI")AP 'di-$%
In#er"s each pixel da"a!
FreeImage-.et<istogram
< +; >+
DLL_API BOOL DLL_CALLCONV FreeImage_(et.istogram(FIBI")AP 'di-0 D7O/D '&isto0 F/ _I)A( _COLO/_C.ANN L c&annel FI_D FA!L"(FICC_BLAC6$$%
3ompu"es "he image his"ogram! For +;:bi" and >+:bi" images, his"ogram can be compu"ed from red, green, blue and black channels! For <:bi" images, his"ogram is compu"ed from "he black channel! O"her bi" dep"h is no" suppor"ed )no"hing is done and "he func"ion re"urns
=# (ppendi)
F(LS2*! The his"o #ariable mus" be alloca"ed by "he applica"ion dri#ing FreeImage! Its si@e is assumed to be eHual to '56!
FreeImage-.et(dKustColorsLoo%up$able
< +; >+
'L!"0 dou-le DLL_API int DLL_CALLCONV FreeImage_(etAd[ustColorsLoo<up"a-le(BA" -rig&tness0 dou-le contrast0 dou-le gamma0 BOOL invert$%
This func"ion crea"es a lookup "able "o be used wi"h FreeImage6(d&us"3ur#e which may ad&us" brigh"ness and con"ras", correc" gamma and in#er" "he image wi"h a single call "o FreeImage6(d&us"3ur#e! If more "han one of "hese image display proper"ies need "o be ad&us"ed, using a combined lookup "able should be preferred o#er calling each ad&us"men" func"ion separa"ely! Tha"Qs par"icularly "rue for huge images or if performance is an issue! Then, "he expensi#e process of i"era"ing o#er all pixels of an image is performed only once and no" up "o four "imes! Fur"hermore, "he lookup "able crea"ed does no" depend on "he order, in which each single ad&us"men" opera"ion is performed! 0ue "o rounding and by"e cas"ing issues, i" ac"ually ma""ers in which order indi#idual ad&us"men" opera"ions are performed! %o"h of "he following snippe"s mos" likely produce differen" resul"s1
++ snippet CX contrast0 -rig&tness FreeImage_Ad[ustContrast(di-0 CEG=$% FreeImage_Ad[ustBrig&tness(di-0 E=G=$% ++ snippet ?X -rig&tness0 contrast FreeImage_Ad[ustBrig&tness(di-0 E=G=$% FreeImage_Ad[ustContrast(di-0 CEG=$%
%e""er and e#en fas"er would be snippe" >1

++ snippet >X BA" L!"P?EDQ% FreeImage_(etAd[ustColorsLoo<up"a-le(L!"0 E=G=0 CEG=0 CG=0 FAL# $% FreeImage_Ad[ustCurve(di-0 L!"0 FICC_/(B$%
This func"ion is also used in"ernally by FreeImage6(d&us"3olors, which does no" re"urn "he lookup "able, bu" uses i" "o call FreeImage6(d&us"3ur#e on "he passed image! -arame"ers follow1
.U- Ou"pu" lookup "able "o be used wi"h FreeImage6(d&us"3ur#e! $he si@e of LL9$L is assumed to be '56! )rig'tness -ercen"age brigh"ness #alue in U:$,,!!$,,V! ( #alue of , means no change, less "han , will make "he image darker and grea"er "han , will make "he image brigh"er! contrast -ercen"age con"ras" #alue in U:$,,!!$,,V! ( #alue of , means no change, less "han , will decrease "he con"ras" and grea"er "han , will increase "he con"ras" of "he image! gamma Eamma #alue "o be used for gamma correc"ion! ( #alue of $!, lea#es "he image alone, less "han one darkens i", and grea"er "han one ligh"ens i"! This parame"er mus" grea"er "han Lero! O"herwise, i" will be ignored and no gamma correc"ion will be performed using "he lookup "able crea"ed! in&ert If se" "o T@72, "he image will be in#er"ed!
The func"ion re"urns "he number of ad&us"men"s applied "o "he resul"ing lookup "able compared "o a blind lookup "able!
(ppendi) =1
FreeImage-(dKustColors
< +; >+
DLL_API BOOL DLL_CALLCONV FreeImage_Ad[ustColors(FIBI")AP 'di-0 dou-le -rig&tness0 dou-le contrast0 dou-le gamma0 BOOL invert FI_D FA!L"(FAL# $$%
This func"ion ad&us"s an imageQs brigh"ness, con"ras" and gamma as well as i" may op"ionally in#er" "he image wi"hin a single opera"ion! If more "han one of "hese image display proper"ies need "o be ad&us"ed, using "his func"ion should be preferred o#er calling each ad&us"men" func"ion separa"ely! Tha"Qs par"icularly "rue for huge images or if performance is an issue! This func"ion relies on FreeImage6Ee"(d&us"3olorsLookupTable, which crea"es a single lookup "able, "ha" combines all ad&us"men" opera"ions reCues"ed! Fur"hermore, "he lookup "able crea"ed by FreeImage6Ee"(d&us"3olorsLookupTable does no" depend on "he order, in which each single ad&us"men" opera"ion is performed! 0ue "o rounding and by"e cas"ing issues, i" ac"ually ma""ers in which order indi#idual ad&us"men" opera"ions are performed! %o"h of "he following snippe"s mos" likely produce differen" resul"s1
++ snippet CX contrast0 -rig&tness FreeImage_Ad[ustContrast(di-0 CEG=$% FreeImage_Ad[ustBrig&tness(di-0 E=G=$% ++ snippet ?X -rig&tness0 contrast FreeImage_Ad[ustBrig&tness(di-0 E=G=$% FreeImage_Ad[ustContrast(di-0 CEG=$%
%e""er and e#en fas"er would be snippe" >1

++ snippet >X FreeImage_Ad[ustColors(di-0 E=G=0 CEG=0 CG=0 FAL# $%
-arame"ers follow1

di) Inpu"8ou"pu" image "o be processed! )rig'tness -ercen"age brigh"ness #alue in U:$,,!!$,,V! ( #alue of , means no change, less "han , will make "he image darker and grea"er "han , will make "he image brigh"er! contrast -ercen"age con"ras" #alue in U:$,,!!$,,V! ( #alue of , means no change, less "han , will decrease "he con"ras" and grea"er "han , will increase "he con"ras" of "he image! gamma Eamma #alue "o be used for gamma correc"ion! ( #alue of $!, lea#es "he image alone, less "han one darkens i", and grea"er "han one ligh"ens i"! This parame"er mus" grea"er "han Lero! O"herwise, i" will be ignored and no gamma correc"ion will be performed using "he lookup "able crea"ed! in&ert If se" "o T@72, "he image will be in#er"ed!
The func"ion re"urns T@72 on success, F(LS2 o"herwise )e!g! when "he bi"deph of "he source dib canno" be handled*!
FreeImage-(pplyColor!apping
$ ; < $= +; >+
DLL_API unsigned DLL_CALLCONV FreeImage_ApplyColor)apping(FIBI")AP 'di-0 /(BM!AD 'srccolors0 /(BM!AD 'dstcolors0 unsigned count0 BOOL ignore_alp&a0 BOOL s;ap$%
=' (ppendi)
(pplies color mapping for one or se#eral colors on a $:, ;: or <:bi" palle"iLed or a $=:, +;: or >+:bi" high color image! This func"ion maps up "o count colors specified in srccolors "o "hese specified in dstcolors! Thereby, color srccolors1N2, if found in "he image, will be replaced by color dstcolors1N2! %o"h arrays srccolors and dstcolors are assumed no" "o hold less "han count colors! If parame"er s ap is T@72, addi"ionally all colors specified in dstcolors are also mapped "o "hese specified in srccolors! For high color images, "he ac"ual image da"a will be modified whereas, for palle"iLed images only "he pale""e will be changed! For $=:bi" images, all colors specified are "ransparen"ly con#er"ed "o "heir proper $=:bi" represen"a"ion )ei"her in @E%PPP or @E%P=P forma", which is de"ermined by "he imageQs red: green: and blue:mask*! :ote, that this behaviour is different from >hat FreeImage-(pply4aletteInde)!apping does, >hich modifies the actual image data on palleti@ed images. -arame"ers follow1

di) Inpu"8ou"pu" image "o be processed! srccolors (rray of colors "o be used as "he mapping source! dstcolors (rray of colors "o be used as "he mapping des"ina"ion! count The number of colors "o be mapped! This is "he siLe of bo"h srccolors and dstcolors! ignore_alp'a If T@72, >+:bi" images and colors are "rea"ed as +;:bi"! s ap If T@72, source and des"ina"ion colors are swapped, "ha" is, each des"ina"ion color is also mapped "o "he corresponding source color!
The func"ion re"urns "he number of pixels changed or Lero, if no pixels were changed!
FreeImage-0>apColors
$ ; < $= +; >+
DLL_API unsigned DLL_CALLCONV FreeImage_#;apColors(FIBI")AP 'di-0 /(BM!AD 'color_a0 /(BM!AD 'color_-0 BOOL ignore_alp&a$%
Swaps "wo specified colors on a $:, ;: or <:bi" palle"iLed or a $=:, +;: or >+:bi" high color image! This func"ion swaps "he "wo specified colors color_a and color_) on a palle"iLed or high color image di)! For high color images, "he ac"ual image da"a will be modified whereas, for palle"iLed images only "he pale""e will be changed! When "he ignore_alp'a parame"er is se" "o T@72, >+:bi" images and colors are "rea"ed as +;:bi"! The func"ion re"urns "he number of pixels changed or Lero, if no pixels were changed! :ote, that this behaviour is different from >hat FreeImage-0>ap4aletteIndices does, >hich modifies the actual image data on palleti@ed images. This func"ion is &us" a "hin wrapper for FreeImage6(pply3olorMapping and resol#es "o1 return FreeImage_*pply3olor,apping(di)/ color_a/ color_)/ 4/ ignore_alp'a/ -%U5)6
FreeImage-(pply4aletteInde)!apping
$ ; <
(ppendi) =3
DLL_API unsigned DLL_CALLCONV FreeImage_ApplyPaletteIndeV)apping(FIBI")AP 'di-0 BA" 'srcindices0 BA" 'dstindices0 unsigned count0 BOOL s;ap$%
(pplies pale""e index mapping for one or se#eral indices on a $:, ;: or <:bi" palle"iLed image! This func"ion maps up "o count pale""e indices specified in srcindices "o "hese specified in dstindices! Thereby, index srcindices1N2, if presen" in "he image, will be replaced by index dstindices1N2! If parame"er s ap is T@72, addi"ionally all indices specified in dstindices are also mapped "o "hese specified in srcindices! %o"h arrays srcindices and dstindices are assumed no" "o hold less "han count indices! :ote, that this behaviour is different from >hat FreeImage-(pplyColor!apping does, >hich modifies the actual image data on palleti@ed images. -arame"ers follow1

di) Inpu"8ou"pu" image "o be processed! srcindices (rray of pale""e indices "o be used as "he mapping source! dstindices (rray of pale""e indices "o be used as "he mapping des"ina"ion! count The number of pale""e indices "o be mapped! This is "he siLe of bo"h srcindices and dstindices! s ap If T@72, source and des"ina"ion pale""e indices are swapped, "ha" is, each des"ina"ion index is also mapped "o "he corresponding source index!
The func"ion re"urns "he number of pixels changed or Lero, if no pixels were changed!
FreeImage-0>ap4aletteIndices
$ ; <
DLL_API unsigned DLL_CALLCONV FreeImage_#;apPaletteIndices(FIBI")AP 'di-0 BA" 'indeV_a0 BA" 'indeV_-$%
Swaps "wo specified pale""e indices on a $:, ;: or <:bi" palle"iLed image! This func"ion swaps "he "wo specified pale""e indices index_a and index_) on a palle"iLed image! Therefore, no" "he pale""e, bu" "he ac"ual image da"a will be modified! The func"ion re"urns "he number of pixels changed or Lero, if no pixels were changed! :ote, that this behaviour is different from >hat FreeImage-0>apColors does on palleti@ed images, >hich only s>aps the colors in the palette. This func"ion is &us" a "hin wrapper for FreeImage6(pply-ale""eIndexMapping and resol#es "o1 return FreeImage_*pply#aletteIndex,apping(di)/ index_a/ index_)/ 4/ -%U5)6
=5 (ppendi)
Channel processing
FreeImage-.etChannel
+; >+ ;<@E%$= =;@E%($= ?=@E%F $+<@E%(F
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_(etC&annel(FIBI")AP 'di-0 F/ _I)A( _COLO/_C.ANN L c&annel$%
@e"rie#es "he red, green, blue or alpha channel of a @E%U(V image! dib is "he inpu" image "o be processed and channel is "he color channel "o ex"rac"! The func"ion re"urns "he ex"rac"ed channel if successful and re"urns D7LL o"herwise!
FreeImage-0etChannel
+; >+ ;<@E%$= =;@E%($= ?=@E%F $+<@E%(F
DLL_API BOOL DLL_CALLCONV FreeImage_#etC&annel(FIBI")AP 'dst0 FIBI")AP 'src0 F/ _I)A( _COLO/_C.ANN L c&annel$%
Inser" a greyscale dib in"o a @E%U(V image! src and dst mus" ha#e "he same wid"h and heigh"! dst is "he des"ina"ion image "o modify, src is "he greyscale image "o inser" and c'annel is "he color channel "o replace! The func"ion re"urns T@72 if successful, F(LS2 o"herwise!
FreeImage-.etComple)Channel
+x=;3OM-L2
DLL_API FIBI")AP ' DLL_CALLCONV FreeImage_(etCompleVC&annel(FIBI")AP 'src0 F/ _I)A( _COLO/_C.ANN L c&annel$%
@e"rie#es "he real par", imaginary par", magni"ude or phase of a complex image )image whose "ype is FIT63OM-L2 *! The func"ion re"urns "he ex"rac"ed channel as a FIT60O7%L2 image if successful and re"urns D7LL o"herwise!
FreeImage-0etComple)Channel
+x=;3OM-L2
DLL_API BOOL DLL_CALLCONV FreeImage_#etCompleVC&annel(FIBI")AP 'dst0 FIBI")AP 'src0 F/ _I)A( _COLO/_C.ANN L c&annel$%
Se" "he real or imaginary par" of a complex image )image whose "ype is FIT63OM-L2 *! %o"h src and ds" mus" ha#e "he same wid"h and heigh"! 7pon en"ry, ds" is "he image "o modify )image of "ype FIT63OM-L2 * and src is "he channel "o replace )image of "ype FIT60O7%L2*! The func"ion re"urns T@72 if successful, F(LS2 o"herwise!
(ppendi) =5
Copy G 4aste G Composite routines

FreeImage-Copy
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Copy(FIBI")AP 'di-0 int le*t0 int top0 int rig&t0 int -ottom$%
3opy a sub par" of "he curren" dib image! The rec"angle defined by "he )lef", "op, righ", bo""om* parame"ers is firs" normaliLed such "ha" "he #alue of "he lef" coordina"e is less "han "he righ" and "he "op is less "han "he bo""om! Then, "he re"urned bi"map is defined by a wid"h eCual "o )righ" : lef"* and a heigh" eCual "o )bo""om : "op*! The func"ion parame"ers follow1 left 1 specifies "he lef" posi"ion of "he cropped rec"angle! top 1 specifies "he "op posi"ion of "he cropped rec"angle! rig't 1 specifies "he righ" posi"ion of "he cropped rec"angle! )ottom 1 specifies "he bo""om posi"ion of "he cropped rec"angle! The func"ion re"urns "he subimage if successful and re"urns D7LL o"herwise!
DormaliLa"ion of "he rec"angle defined by "he )lef", "op, righ", bo""om* parame"ers means "ha" "he coordina"e sys"em uses usual graphics con#en"ions! This is used "o ease in"erac"ions wi"h a mouse!
FreeImage-4aste
DLL_API BOOL DLL_CALLCONV FreeImage_Paste(FIBI")AP 'dst0 FIBI")AP 'src0 int le*t0 int top0 int alp&a$%
(lpha blend or combine a sub par" image wi"h "he curren" dib image! For images of "ype FIT%ITM(- only1 The bi" dep"h of "he dst bi"map mus" be grea"er "han or eCual "o "he bi" dep"h of "he src! 7pper promo"ion of src is done in"ernally, wi"hou" modifying src! Suppor"ed dst bi" dep"h eCuals "o $, ;, <, $=, +; or >+! For any o"her image "ype1 The image "ype of "he dst bi"map mus" be eCual "o "he image "ype of "he src! The alp'a parame"er is always ignored and "he source image is combined "o "he des"ina"ion image! -arame"ers follow1 dst 1des"ina"ion image src 1 source subimage left 1 specifies "he lef" posi"ion of "he sub image! top 1 specifies "he "op posi"ion of "he sub image! alp'a 1 alpha blend fac"or! The source and des"ina"ion images are alpha blended if alphaS,!!+PP! If alpha O +PP, "hen "he source image is combined "o "he des"ina"ion image! The func"ion re"urns T@72 if successful, F(LS2 o"herwise!
=6 (ppendi)
Bou canno" perform pas"e opera"ions be"ween pale""iLed images, unless bo"h src and ds" images use "he same pale""e! For bi" dep"hs less "han or eCual "o <:bi", pas"e opera"ions usually only work wi"h greyscale images!
3oordina"e sys"em defined by "he )lef", "op* parame"ers uses usual graphics con#en"ions! This is used "o ease in"erac"ions wi"h a mouse!
(ppendi) ="
FreeImage-Composite
< >+
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Composite(FIBI")AP '*g0 BOOL useFileB<g FI_D FA!L"(FAL# $0 /(BM!AD 'appB<Color FI_D FA!L"(N!LL$0 FIBI")AP '-g FI_D FA!L"(N!LL$$%
This func"ion composi"e a "ransparen" foreground image agains" a single background color or agains" a background image! 7pon en"ry, fg defines "he foreground image and "he "ransparency mask )implici"ly included in "he foreground image as a "ransparency "able for <: bi" dib or as a alpha channel for >+:bi" dib*! The eCua"ion for compu"ing a composi"ed sample #alue is1 output 0 alp'a 7 foreground 8 (4(alp'a) 7 )ac!ground where alpha and "he inpu" and ou"pu" sample #alues are expressed as frac"ions in "he range , "o $! For colour images, "he compu"a"ion is done separa"ely for @, E, and % samples! The following pseudo:code illus"ra"es "he in"ernal use of "he o"her parame"ers1
i*(useFileB<g II FreeImage_.asBac<groundColor(*g$$ 1 ++ !se t&e *ile -ac<ground as t&e single -ac<ground color 9 else 1 ++ no *ile -ac<ground color : ++ use application -ac<ground color \ i*(appB<Color$ 1 ++ use t&e application -ac<ground as t&e single -ac<ground color 9 ++ no application -ac<ground color : ++ use a -ac<ground image \ else i*(-g$ 1 ++ use -g as t&e -ac<ground image ++ -g )!#" B a ?@T-it image ;it& t&e same ;idt& and &eig&t as *g 9 else 1 ++ de*ault case ++ use a c&ec<er-oard as t&e -ac<ground image 9 9
1a2
1b2
1c2
Figure 1* Illustration of the FreeImage-Composite function. (n illus"ra"ion of "he FreeImage63omposi"e func"ion is gi#en in Figure $! This sample image is a <:bi" "ransparen" -DE wi"h a ligh":blue file color background! 2ach image was genera"ed using "he following calls1
=& (ppendi)
FIBI")AP '*g 5 FreeImage_Load(FIF_PN(0 FtestGpngH0 PN(_D FA!L"$% ++ image (a$ X use a c&ec<er-oard -ac<ground FIBI")AP 'display_di-_a 5 FreeImage_Composite(*g$% ++ image (-$ X use t&e image *ile -ac<ground i* t&ere is one FIBI")AP 'display_di-_- 5 FreeImage_Composite(*g0 "/! $% ++ image (c$ X use a user speci*ied -ac<ground /(BM!AD appColor 5 1 =0 ?EE0 =0 = 9% FIBI")AP 'display_di-_c 5 FreeImage_Composite(*g0 FAL# 0 IappColor$%
+eference -or"able De"work Eraphics )-DE* Specifica"ion )Second 2di"ion*! UOnlineV h""p188www!w>!org8T@8-DE8
FreeImage-?4,.Crop
DLL_API BOOL DLL_CALLCONV FreeImage_ZP (Crop(const c&ar 'src_*ile0 const c&ar 'dst_*ile0 int le*t0 int top0 int rig&t0 int -ottom$%
-erforms a lossless crop on a J-2E file! 7pon en"ry, src6file is "he source J-2E file and ds"6file "he des"ina"ion J-2E file! 7sing "he same file for source and des"ina"ion is allowed1 "he source file will be "ransformed and o#erwri""en! The rec"angle defined by "he )lef", "op, righ", bo""om* parame"ers is firs" normaliLed such "ha" "he #alue of "he lef" coordina"e is less "han "he righ" and "he "op is less "han "he bo""om! Then, "he re"urned bi"map is defined by a wid"h grea"er "han or eCual "o )righ" : lef"* and a heigh" grea"er "han or eCual "o )bo""om : "op* Y see "he explana"ion below! The func"ion parame"ers follow1 left 1 specifies "he lef" posi"ion of "he cropped rec"angle! top 1 specifies "he "op posi"ion of "he cropped rec"angle! rig't 1 specifies "he righ" posi"ion of "he cropped rec"angle! )ottom 1 specifies "he bo""om posi"ion of "he cropped rec"angle! FreeImage6J-2E3rop works by rearranging "he compressed da"a )03T coefficien"s*, wi"hou" e#er fully decoding "he image! Therefore, "he crop opera"ion is lossless1 "here is no image degrada"ion a" all, which would no" be "rue if you used FreeImage_.oad followed by FreeImage_$a&e "o accomplish "he same con#ersion! To perform "his lossless opera"ion, howe#er, "he wid"h and heigh" of "he cropped rec"angle mus" be ad&us"ed so "ha" "he image dimensions are a mul"iple of "he iM37 siLe )usually < or $= pixels*, because "he func"ion can only "ransform comple"e blocks of 03T coefficien" da"a in "he desired way! Tha"'s why "he ou"pu" wid"h or heigh" can be sligh"ly grea"er "han "he reCues"ed image siLe!
FreeImage-?4,.Crop9
DLL_API BOOL DLL_CALLCONV FreeImage_ZP (Crop!(const ;c&ar_t 'src_*ile0 const ;c&ar_t 'dst_*ile0 int le*t0 int top0 int rig&t0 int -ottom$%
This func"ion works exac"ly like FreeImage6J-2E3rop 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"ion does no"hing and re"urns F(LS2!
(ppendi) ==
FreeImage-4re!ultiplyEith(lpha
>+
DLL_API BOOL DLL_CALLCONV FreeImage_Pre)ultiply7it&Alp&a(FIBI")AP 'di-$%
-re:mul"iplies a >+:bi" imageQs red:, green: and blue channels wi"h i"Qs alpha channel for "o be used wi"h "he Windows E0I func"ion (lpha%lend)*! The "ransforma"ion changes "he red:, green: and blue channels according "o "he following eCua"ion1 c'annel(x/ y) 0 c'annel(x/ y) 7 alp'a_c'annel(x/ y) 9 :;; The func"ion re"urns T@72 on success, F(LS2 o"herwise )e!g! when "he bi"dep"h of "he source dib canno" be handled*!
1## (ppendi)
ac%ground filling
FreeImage-Fill ac%ground
DLL_API BOOL DLL_CALLCONV FreeImage_FillBac<ground(FIBI")AP 'di-0 const void 'color0 int options FI_D FA!L"(=$$%
This func"ion se"s all pixels of an image "o "he color pro#ided "hrough "he color parame"er! -arame"ers follow1 di) The image "o be filled! color ( poin"er "o "he color #alue "o be used for filling "he image! The memory poin"ed "o by "his poin"er is always assumed "o be a" leas" as large as "he imageQs color #alue, bu" ne#er smaller "han "he siLe of an @E%X7(0 s"ruc"ure! options Op"ions "ha" affec" "he color search process for palle"iLed images!
The func"ion re"urns T@72 on success, F(LS2 o"herwise! This func"ion fails if any of di) and color is D7LL!
The color poin"er mus" poin" "o a memory loca"ion which is a" leas" ;:by"es for FIT6%ITM(- "ypes, and a" leas" as large as "he imageQs color #alue, if "his siLe is grea"er "han ; by"es!
FI$- I$!(4 image type The color parame"er M7ST %2 specified "hrough a @E%X7(0 s"ruc"ure for all images of "ype FIT6%ITM(- )including all palle"iLed images*, "he siLe of "his memory is "hus "he siLe of "he @E%X7(0 s"ruc"ure, which uses ; by"es! 24- and 32-bit images For +;: and >+:bi" images, "he red, green and blue members of "he @E%X7(0 s"ruc"ure are direc"ly used for "he imageQs red, green and blue channel respec"i#ely! (l"hough alpha "ransparen" @E%X7(0 colors are suppor"ed, "he alpha channel of a >+:bi" image ne#er ge"s modified by "his func"ion! ( fill color wi"h an alpha #alue smaller "han +PP ge"s blended wi"h "he imageQs ac"ual background color, which is de"ermined from "he imageQs bo""om:lef" pixel! So, curren"ly using alpha enabled colors, assumes "he image "o be unicolor before "he fill opera"ion! .owe#er, "he @E%X7(0Qs rgb@eser#ed member is only "aken in"o accoun", if op"ion FI_3O.O%_I$_%G<*_3O.O% has been specified! 4arameter
FI63OLO@6IS6@E%(63OLO@
Description
@E%X7(0 color is a @E%( color )con"ains a #alid alpha channel*
$able 1"* ac%ground filling options for '57 or 3'7bit images 16-bit RGB images For $=:bi" @E% images, "he red:, green: and blue componen"s of "he specified color are "ransparen"ly "ransla"ed in"o ei"her "he $=:bi" PPP or P=P represen"a"ion! This depends on "he imageQs ac"ual red: green: and blue masks! 1-, 4- or 8-bit palletized images
(ppendi) 1#1
Special a""en"ion mus" be payed for palle"iLed images! Eenerally, "he @E% color specified is looked up in "he imageQs pale""e! The found pale""e index is "hen used "o fill "he image! There are some option flags "ha" affec" "his lookup process! 4arameter
FI63OLO@6IS6@E%63OLO@
Description
7ses "he color "ha" is neares" "o "he specified color! This is "he defaul" beha#ior and should always find a color in "he pale""e! .owe#er, "he #isual resul" may be far from wha" was expec"ed and mainly depends on "he imageQs pale""e! Searches "he imageQs pale""e for "he specified color bu" only uses "he re"urned pale""e index, if "he specified color exac"ly ma"ches "he pale""e en"ry! Of course, depending on "he imageQs ac"ual pale""e en"ries, "his opera"ion may fail! In "his case, "he func"ion falls back "o op"ion FI63OLO@6(L-.(6IS6ID02 and uses "he @E%X7(0Qs rgb@eser#ed member )or i"s low nibble for ;:bi" images or i"s leas" significan" bi" )LS%* for $:bi" images* as "he pale""e index used for "he fill opera"ion! The colorQs rgb@eser#ed member )alpha* con"ains "he pale""e index "o be used 3ombina"ion of (FI_COLO/_FIND_ M!AL_COLO/ _ FI_COLO/_ALP.A_I#_IND R$ Do color lookup is performed
FI63OLO@6FID062X7(L63OLO@
FI63OLO@6(L-.(6IS6ID02
FI63OLO@6-(L2TT26S2(@3.6M(SI
$able 1&* ac%ground filling options for palleti@ed images (ny other image types The color parame"er M7ST poin" "o a double, if "he image "o be filled is of "ype FIT60O7%L2, poin" "o a @E%U(V$= s"ruc"ure if "he image is of "ype @E%U(V$=, poin" "o a @E%U(VF s"ruc"ure if "he image is of "ype FIT6@E%U(VF and so on!
FreeImage-,nlargeCanvas
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_ nlargeCanvas(FIBI")AP 'src0 int le*t0 int top0 int rig&t0 int -ottom0 const void 'color0 int options$%
2nlarges or shrinks an image selec"i#ely per side and fills newly added areas wi"h "he specified background color! -arame"ers follow1 di) The image "o be enlarged or shrunken! left The number of pixels, "he image should be enlarged on i"s lef" side! Dega"i#e #alues shrink "he image on i"s lef" side! top The number of pixels, "he image should be enlarged on i"s "op side! Dega"i#e #alues shrink "he image on i"s "op side! rig't The number of pixels, "he image should be enlarged on i"s righ" side! Dega"i#e #alues shrink "he image on i"s righ" side! )ottom The number of pixels, "he image should be enlarged on i"s bo""om side! Dega"i#e #alues shrink "he image on i"s bo""om side! color The color, "he enlarged sides of "he image should be filled wi"h! options Op"ions "ha" affec" "he color search process for palle"iLed images!
The func"ion re"urns a poin"er "o a newly alloca"ed enlarged or shrunken image on success, D7LL o"herwise! This func"ion fails if ei"her "he inpu" image is D7LL or "he poin"er "o "he color is D7LL, while a" leas" one of lef", "op, righ" and bo""om is grea"er "han Lero! This func"ion also re"urns D7LL, if "he new imageQs siLe will be nega"i#e in ei"her x: or y:direc"ion!
1#' (ppendi)
This func"ion enlarges or shrinks an image selec"i#ely per side! The main purpose of "his func"ion is "o add borders "o an image! To add a border "o any of "he imageQs sides, a posi"i#e in"eger #alue mus" be passed in any of "he parame"ers lef", "op, righ" or bo""om! This #alue represen"s "he borderQs wid"h in pixels! Dewly crea"ed par"s of "he image )"he border areas* are filled wi"h "he specified color! Specifying a nega"i#e in"eger #alue for a cer"ain side, will shrink or crop "he image on "his side! 3onseCuen"ly, specifying Lero for a cer"ain side will no" change "he imageQs ex"ension on "ha" side! So, calling "his func"ion wi"h all parame"ers lef", "op, righ" and bo""om se" "o Lero, is effec"i#ely "he same as calling func"ion FreeImage63loneM se""ing all parame"ers lef", "op, righ" and bo""om "o #alue eCual "o or smaller "han Lero, may easily be subs"i"u"ed by a call "o func"ion FreeImage63opy! %o"h "hese cases produce a new image, which is guaran"eed no" "o be larger "han "he inpu" image! Thus, since "he specified color is no" needed in "hese cases, "he poin"er color may be D7LL! %o"h parame"ers color and options work according "o func"ion FreeImage6Fill%ackground! So, please refer "o "he documen"a"ion of FreeImage6Fill%ackground "o learn more abou" parame"ers color and options! For palle"iLed images, "he pale""e of "he inpu" image src is "ransparen"ly copied "o "he newly crea"ed enlarged or shrunken image, so any color look:ups are performed on "his pale""e! .ere are some examples "ha" illus"ra"e how "o use "he parame"ers left, top, rig't and )ottom1
++ create a ;&ite color /(BM!AD c% cGrg-/ed 5 =VFF% cGrg-(reen 5 =VFF% cGrg-Blue 5 =VFF% cGrg-/eserved 5 =V==% ++ add a ;&ite0 symmetric C= piVel ;ide -order to t&e image di-? 5 FreeImage_ nlargeCanvas(di-0 C=0 C=0 C=0 C=0 Ic0 FI_COLO/_I#_/(B_COLO/$% ++ add ;&ite0 ?= piVel ;ide stripes to t&e top and -ottom side o* t&e image di-> 5 FreeImage_ nlargeCanvas(di-0 =0 ?=0 =0 ?=0 Ic0 FI_COLO/_I#_/(B_COLO/$% ++ add ;&ite0 >= piVel ;ide stripes to t&e rig&t side o* t&e image and ++ cut o** t&e @= le*tmost piVel columns di-> 5 FreeImage_ nlargeCanvas(di-0 T@=0 =0 >=0 =0 Ic0 FI_COLO/_I#_/(B_COLO/$%
FreeImage-(llocate,)
$ ; < $= +; >+
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Allocate V(int ;idt&0 int &eig&t0 int -pp0 const /(BM!AD 'color0 int options0 const /(BM!AD 'palette0 unsigned red_mas< FI_D FA!L"(=$0 unsigned green_mas< FI_D FA!L"(=$0 unsigned -lue_mas< FI_D FA!L"(=$$%
(lloca"es a new image of "he specified wid"h, heigh" and bi" dep"h and op"ionally fills i" wi"h "he specified color!
FreeImage6(lloca"e2x is an alias for FreeImage6(lloca"e2xT and can be replaced by "his call1 FreeImage6(lloca"e2x"T)FIT6%ITM(-, wid"h, heigh", bpp, color, op"ions, pale""e, red6mask, green6mask, blue6mask*M
FreeImage-(llocate,)$
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_Allocate V"(F/ _I)A( _"AP type0 int ;idt&0 int &eig&t0 int -pp0 const void 'color0 int options0 const /(BM!AD 'palette0 unsigned red_mas< FI_D FA!L"(=$0 unsigned green_mas< FI_D FA!L"(=$0 unsigned -lue_mas< FI_D FA!L"(=$$%
(ppendi) 1#3
(lloca"es a new image of "he specified "ype, wid"h, heigh" and bi" dep"h and op"ionally fills i" wi"h "he specified color! -arame"ers follow1 type Specifies "he image "ype of "he new image! idt' The desired wid"h in pixels of "he new image! 'eig't The desired heigh" in pixels of "he new image! )pp The desired bi" dep"h of "he new image! color ( poin"er "o "he color #alue "o be used for filling "he image! The memory poin"ed "o by "his poin"er is always assumed "o be a" leas" as large as "he imageQs color #alue bu" ne#er smaller "han "he siLe of an @E%X7(0 s"ruc"ure! options Op"ions "ha" affec" "he color search process for palle"iLed images! red_mas! Specifies "he bi"s used "o s"ore "he red componen"s of a pixel! green_mas! Specifies "he bi"s used "o s"ore "he green componen"s of a pixel! )lue_mas! Specifies "he bi"s used "o s"ore "he blue componen"s of a pixel!
The func"ion re"urns a poin"er "o a newly alloca"ed image on success, re"urns D7LL o"herwise!
This func"ion is an ex"ension "o FreeImage6(lloca"eT, which addi"ionally suppor"s specifying a pale""e "o be se" for "he newly crea"ed image, as well as specifying a background color, "he newly crea"ed image should ini"ially be filled wi"h!
%asically, "his func"ion in"ernally relies on func"ion FreeImage6(lloca"eT, followed by a call "o FreeImage6Fill%ackground! This is why bo"h parame"ers color and options beha#e "he same as i" is documen"ed for func"ion FreeImage6Fill%ackground! So, please refer "o "he documen"a"ion of FreeImage6Fill%ackground "o learn more abou" parame"ers color and options! The pale""e specified "hrough parame"er palette is only copied "o "he newly crea"ed image, if i"s image "ype is FIT6%ITM(- and "he desired bi" dep"h is smaller "han or eCual "o <:bi" per pixel! In o"her words, "he palette parame"er is only "aken in"o accoun" for palle"iLed images! .owe#er, if "he preceding condi"ions ma"ch and if palette is no" D7LL, "he memory poin"ed "o by "he palette poin"er is assumed "o be a" leas" as large as siLe of a fully popula"ed pale""e for "he desired bi" dep"h! So, for an <:bi" image, "his siLe is +P= x siLeof)@E%X7(0*, for an ;:bi" image i" is $= x siLeof)@E%X7(0* and i" is + x siLeof)@E%X7(0* for a $:bi" image! In o"her words, "his func"ion does no" suppor" par"ial pale""es! .owe#er, specifying a pale""e is no" necessarily needed, e#en for palle"iLed images! This func"ion is capable of implici"ly crea"ing a pale""e, if parame"er pale""e is D7LL! If "he specified background color is a greyscale #alue )red S green S blue* or if op"ion FI63OLO@6(L-.(6IS6ID02 is specified, a greyscale pale""e is crea"ed! For a $:bi" image, only if "he specified background color is ei"her black or whi"e, a monochrome pale""e, consis"ing of black and whi"e only is crea"ed! In any case, "he darker colors are s"ored a" "he smaller pale""e indices! If "he specified background color is no" a greyscale #alue, or is nei"her black nor whi"e for a $: bi" image, solely "his single color is in&ec"ed in"o "he o"herwise black:ini"ialiLed pale""e! For "his opera"ion, op"ion FI63OLO@6(L-.(6IS6ID02 is implici", so "he specified color is applied "o "he pale""e en"ry, specified by "he background colorQs rgb@eser#ed member! The image is "hen filled wi"h "his pale""e index! This func"ion re"urns a newly crea"ed image as func"ion FreeImage6(lloca"eT does, if bo"h parame"ers color and palette are D7LL! If only color is D7LL, "he pale""e poin"ed "o by parame"er palette is ini"ially se" for "he new image, if a palle"iLed image of "ype FIT6%ITM(is crea"ed! .owe#er, in "he la""er case, "his func"ion re"urns an image, whose pixels are all ini"ialiLed wi"h Leros so, "he image will be filled wi"h "he color of "he firs" pale""e en"ry!
1#5 (ppendi)
(ppendi) 1#5
!iscellaneous algorithms
FreeImage-!ultigrid4oisson0olver
>+FLO(T
DLL_API FIBI")AP 'DLL_CALLCONV FreeImage_)ultigridPoisson#olver(FIBI")AP 'Laplacian0 int ncycle FI_D FA!L"(>$$%
-oisson sol#er based on a mul"igrid algori"hm! This rou"ine sol#es a -oisson eCua"ion, remap resul" pixels "o U,!!$V and re"urns "he solu"ion as a FIT6FLO(T image "ype! In"ernally, "he inpu" image is firs" s"ored inside a sCuare image whose siLe is )+ & 9 $* x )+& 9 $* for some in"eger &, where & is such "ha" + & is "he neares" larger dimension corresponding "o M( )image wid"h, image heigh"*! .owe#er, "he resul"ing ou"pu" image will ha#e "he same siLe )wid"h and heigh"* as "he inpu" image! -arame"ers follows1 .aplacian Laplacian image ncycle Dumber of cycles in "he mul"igrid algori"hm )usually + or >* The func"ion re"urns "he sol#ed -02 eCua"ions if successful, re"urns D7LL o"herwise! +eference -ress, W! .!, Teukolsky, S! (!, 4e""erling, W! T!, and Flannery, %! -!, Dumerical @ecipes in 31 The (r" of Scien"ific 3ompu"ing, +nd ed! 3ambridge 7ni#ersi"y -ress! $??+!
1#6 (ppendi)
(ppendi)
0upported file formats

The following "able shows "he capabili"ies of each FreeImage plugin!
0944/+$ $+(:04(+,:C3
0944/+$ <,(D,+ /:L3
0944/+$ ICC 4+/FIL,0
0944/+$ L/(DI:.
,F4/+$,D $34, FI$-C/!4L,F FI$-D/9 L,
F/+!($
D,0C+I4$I/:
,F$,:0I/:0
0944/+$ /4$I/:0
0944/+$ E+I$I:.
,F4/+$,D I$D,4$<
FI$-+. (16
FI$- I$!(4
FIF6%MFIF637T FIF600S FIF62 @ FIF6F( E> FIF6EIF FIF6.0@ FIF6I3O FIF6IFF FIF6J+I FIF6JDE FIF6J-+ FIF6J-2E FIF6IO(L( FIF6MDE FIF6-%M FIF6-%M@(W FIF6-30 FIF6-3 FIF6-FM FIF6-EM FIF6-EM@(W FIF6-I3T FIF6-DE FIF6--M FIF6--M@(W FIF6-S0 FIF6@(S FIF6@(W FIF6SEI FIF6T(@E( FIF6TIFF FIF6W%MFIF6 %M FIF6 -M Legend* yes 1 no 1 :
Windows or OS8+ %i"map 0r! .alo 0irec" Surface ILM Open2 @ @aw fax forma" 33ITT E!> Eraphics In"erchange Forma" .igh 0ynamic @ange Windows Icon IFF In"erlea#ed %i"map J-2E:+,,, codes"ream J-2E De"work Eraphics J-2E:+,,, File Forma" J-2E : JFIF 3omplian" 3=; Ioala Eraphics Mul"iple De"work Eraphics -or"able %i"map )(S3II* -or"able %i"map )@(W* Iodak -ho"o30 Ksof" -ain"brush -or"able Floa"map -or"able Ereymap )(S3II* -or"able Ereymap )@(W* Macin"osh -I3T -or"able De"work Eraphics -or"able -ixelmap )(S3II* -or"able -ixelmap )@(W* (dobe -ho"oshop Sun @as"er Image @(W camera image Silicon Eraphics SEI image forma" True#ision Targa Tagged Image File Forma" Wireless %i"map $$ %i"map Forma" $$ -ixmap Forma"
dds exr g> gif hdr ico iff,lbm &+k,&+c &ng &p+ &pg,&if,&peg,&pe koa mng pbm pbm pcd pcx pfm pgm pgm pc",pic",pic png ppm ppm psd ras many sgi "ga,"arga "if,"iff wap,wbmp,wbm xbm xpm
bmp cu"
: :
: :
: : : : :
: : : : : :
: : : : : : : : : : : :
: : : : : : : : : : : :
: : : : : :
: : : : : :
: : : :
: : : : : :
: : : : : :
: : : : : :
: : : :
: : : : : : : : :
: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :
: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :
: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :
: : :
: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :
: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :
: : : : : : : : :
: : : : : : : : :
FI$-+. F : : :
FI$-I:$16
FI$-I:$3'
&
3'
&
16
'5
3'
: : : : : : : : : : : : : : :
: :
: : : : : : : : : : : : : : : : :
: : : : : : :
: : : : : : : : : : : : : : :
: : : : : : : : : : : : : : : : : : : : : :
: : : : : : : : : : : :

: :

: :
: : : : : : : : : : :
: : : : : : : : : :
: : : :

: : : : : : :

: : : : : : : : : :
: : : : : : : : : : :

: :
: : : : : : : :
: : : : : : : : : : :
: : : : : : : : : : :

: :

: :

: : : :

: : : : : :

: : :
: : : : : : : : : : :
: : : : : : : : : : :

: : : :

: :
: : : : : :
: : : : : :
: : : : : : :
: :
: : : : : : :
: : : : : : :
: : : : : :
: : :

: : : :
: : : : : :

: : : :
: : : : : : :

: : : : :
: : : : : : :

: : :

: : :

: : :
: : :

: : :

: :
: : :

: : :
: : : :

: :

: : :
: : :
: : :
: : :
: : :
: : :
: : :
: : :
: : :
: : :
: : :
(ppendi) 1#"
FI$-+. (F : : :
FI$-9I:$16
FI$-9I:$3'
FI$-FL/($
FI$-+. 16
: : : : : : : : : : : : : : : : : : : : : : : : : : :
: : :
0upported camera +(E file formats

The following "able shows a non e)haustive list of "he camera @(W forma"s suppor"ed by "he @(W plugin! Do"e "ha" o"hers forma"s may be suppor"ed )"he @(W file forma" ex"ension lis" produced by camera manufac"urers is no" documen"ed*!
,F$,:0I/: >fr arw bay bmC cap cine cr+ crw cs$ dc+ dcr dng drf dsc erf fff hdr ia iiC k+P kc+ kdc mdc mef mos mrw nef nrw orf pef p"x pxn C"k raf raw rdc rw+ rwL sr+ srf s"i x>f D,0C+I4$I/: .asselblad 0igi"al 3amera @aw Image Forma"! Sony 0igi"al 3amera @aw Image Forma" for (lpha de#ices! 3asio 0igi"al 3amera @aw File Forma"! Du3ore @aw Image File! -hase One 0igi"al 3amera @aw Image Forma"! -han"om Sof"ware @aw Image File! 3anon 0igi"al 3amera @(W Image Forma" #ersion +!,! These images are based on "he TIFF image 3anon 0igi"al 3amera @(W Image Forma" #ersion $!,! 3ap"ure Shop @aw Image File! Iodak 03+P 0igi"al 3amera File! Iodak 0igi"al 3amera @aw Image Forma" for "hese models1 Iodak 0S3 -ro SL@8c, Iodak 0S3 -ro SL@8n, Iodak 0S3 -ro $;D, Iodak 0S3 -@O $;nx! (dobe 0igi"al Dega"i#e1 0DE is publicly a#ailable archi#al forma" for "he raw files genera"ed by digi"al cameras! %y addressing "he lack of an open s"andard for "he raw files crea"ed by indi#idual camera models, 0DE helps ensure "ha" pho"ographers will be able "o access "heir files in "he fu"ure! Iodak 0igi"al 3amera @aw Image Forma"! Iodak 0igi"al 3amera @aw Image Forma"! 2pson 0igi"al 3amera @aw Image Forma"! Imacon 0igi"al 3amera @aw Image Forma"! Leaf @aw Image File! Sinar @aw Image File! -hase One 0igi"al 3amera @aw Image Forma"! Iodak 03+P 0igi"al 3amera @aw Image Forma"! Iodak 03S+,, 0igi"al 3amera @aw Image Forma"! Iodak 0igi"al 3amera @aw Image Forma"! Minol"a @0$TP 0igi"al 3amera @aw Image Forma"! Mamiya 0igi"al 3amera @aw Image Forma"! Mamiya 0igi"al 3amera @aw Image Forma"! Minol"a 0image 0igi"al 3amera @aw Image Forma"! Dikon 0igi"al 3amera @aw Image Forma"! Dikon 0igi"al 3amera @aw Image Forma"! Olympus 0igi"al 3amera @aw Image Forma"! -en"ax 0igi"al 3amera @aw Image Forma"! -en"ax 0igi"al 3amera @aw Image Forma"! Logi"ech 0igi"al 3amera @aw Image Forma"! (pple Xuick"ake $,,8$P, 0igi"al 3amera @aw Image Forma"! Fu&i 0igi"al 3amera @aw Image Forma"! -anasonic 0igi"al 3amera Image Forma"! 0igi"al Fo"o Maker @aw Image File! -anasonic L > 0igi"al 3amera @aw Image Forma"! @awLor 0igi"al 3amera @aw Image Forma"! Sony 0igi"al 3amera @aw Image Forma"! Sony 0igi"al 3amera @aw Image Forma" for 0S3:F<+< < megapixel digi"al camera or Sony 0S3:@$ Sinar 3ap"ure Shop @aw Image File! Sigma 0igi"al 3amera @aw Image Forma" for de#ices based on Fo#eon > direc" image sensor! 7nsuppor"ed because of license res"ric"ions!
1#& (ppendi)
Choosing the right resampling filter

The effec" of a resampling fil"er is highly dependan" on "he physical charac"eris"ics of "he image being resiLed! De#er"heless, "he following hin"s may pro#e helpful when deciding which fil"er "o use!
o) filter
%ox scaling is "he simples" and fas"es" of "he scaling algori"hms, from a compu"a"ional s"andpoin"! 4arious names are used "o deno"e "his simple kernel! They include "he box fil"er, sample:and:hold func"ion, pulse func"ion, Fourier window, $s" order )cons"an"* %:Spline and neares" neighbour! The "echniCue achie#es magnifica"ion by pixel replica"ion, and minifica"ion by sparse poin" sampling! For large:scale changes, box in"erpola"ion produces images wi"h a blocky appearance! In addi"ion, shif" errors of up "o one:half pixel are possible! These problems make "his "echniCue inappropria"e when sub:pixel accuracy is reCuired!
ilinear filter
%ilinear scaling is "he second:fas"es" scaling func"ion! I" employs linear in"erpola"ion "o de"ermine "he ou"pu" image! %ilinear scaling pro#ides reasonably good resul"s a" modera"e cos" for mos" applica"ions where scale fac"ors are rela"i#ely small ); or less*! Of"en, "hough, higher fideli"y is reCuired and "hus more sophis"ica"ed fil"ers ha#e been formula"ed!
70pline filter
The %:spline fil"er produces "he smoo"hes" ou"pu", bu" "ends "o smoo"h o#er fine de"ails! This func"ion reCuires "he same processing "ime as Mi"chell and De"ra#ali's %icubic fil"er! %:spline fil"er is recommended for applica"ions where "he smoo"hes" ou"pu" is reCuired!
icubic filter
Mi"chell and De"ra#ali's bicubic fil"er is an ad#anced parame"eriLed scaling fil"er! I" uses a cubic func"ion "o produce #ery smoo"h ou"pu" while main"aining dynamic range and sharpness! %icubic scaling "akes approxima"ely "wice "he processing "ime as %ilinear! This fil"er can be used for any scaling applica"ion, especially when scaling fac"ors are + or grea"er!
Catmull7+om filter
When using Mi"chell:De"ra#ali fil"ers, you ha#e "o se" "wo parame"ers b and c such "ha" b 9 +c S $, in order "o use "he numerically mos" accura"e fil"er! The %icubic fil"er uses "he defaul" #alues )b S $8>, c S $8>*, which were "he #alues recommended by Mi"chell and De"ra#ali as yielding "he mos" #isually pleasing resul"s in sub&ec"i#e "es"s of human beings! When b S ,, "his gi#es "he maximum #alue for c S ,!P, which is "he 3a"mull:@om spline and a good sugges"ion for sharpness! The 3a"mull:@om fil"er is generally accep"ed as "he best cubic interpolant filter!
Lanc@os filter
LancLos uses a fil"er based on "he sinc func"ion! This is "he mos" "heore"ically correc" fil"er and produces "he bes" ou"pu" for pho"ographic images "ha" do no" ha#e sharp "ransi"ions in
(ppendi) 1#=
"hem! .owe#er, LancLos will produce ripple ar"efac"s especially for block "ex", due "o aliasing! LancLos also reCuires "hree "imes "he processing "ime of %ilinear! LancLos is no" recommended excep" in #ery rare applica"ions using band:limi"ed pho"ographic images wi"h no sharp edges!
Comparison of resampling methods
Original .ena image
%ox fil"er
%ilinear fil"er
3ubic %:Spline fil"er
%icubic fil"er 3a"mull:@om fil"er LancLos fil"er Figure '* Comparison of resampling filters on a 3')3' Lena image resi@ed to 5##A.
11# (ppendi)
Original <i!ini image
%ox fil"er
%ilinear fil"er
3ubic %:Spline fil"er
Mi"chell and De"ra#aliQs bicubic fil"er
(ppendi) 111
3a"mull:@om fil"er
LancLos> fil"er
Figure 3* Comparison of resampling filters on a 5#)56 i%ini image resi@ed to &##A.
11' (ppendi)
9sing the rotation functions

FreeImage-+otate
The following figure demons"ra"es "he resul" of using FreeImage6@o"a"e when ro"a"ing an image by an angle of ;P]! Do"e "ha" "he ro"a"ed image is larger "han "he original image!
Original #arrot image @o"a"ed image Figure 5* 4arrot image rotated by 55B using FreeImage-+otate. The same image now ro"a"ed by an angle of ?,] is showed in Figure P! This "ime, "he ro"a"ed image has "he same siLe as "he original one!
Figure 5* 4arrot image rotated by =#B using FreeImage-+otate.
(ppendi) 113
FreeImage-+otate,)
Figure = shows some of "he resul"s you can ob"ain wi"h "he FreeImage6@o"a"e2x func"ion!
Original +P=x+P= .ena image
)a*
)b*
)c*
Figure 6* 0ome e)amples illustrating the use of FreeImage-+otate,). 1 a 2 1 Image resul"ing from an arbi"rary "ransforma"ion )no masking*! The image has been ro"a"ed by some angle around an arbi"rary origin, while an addi"ional "ransla"ion has been "hrown in for good measure! Obser#e "he influence of mirroring "he da"a )"he func"ion allows for "he masking ou" of "he ex"rapola"ed da"a, if desired*! FIBI")AP 'dst 5 FreeImage_/otate V(src0 V_origin0 y_origin0 FAL# $% angle0 V_s&i*t0 y_s&i*t0
1 b 2 1 Image resul"ing from a simple in"eger "ransla"ion using "he following code 1 FIBI")AP 'dst 5 FreeImage_/otate V(src0 =0 T?=0 >=0 =0 =0 "/! $% This "ime, we se" "he use_mas! parame"er "o T@72, "o mask ou" "he irrele#an" par" of "he image! 1 c 2 1 Image resul"ing from a ro"a"ion around "he upper:lef" corner 1
115 (ppendi)
FIBI")AP 'dst 5 FreeImage_/otate V(src0 CE0 =0 =0 =0 =0 "/! $%
(ppendi) 115
FreeImage metadata models

FI!D-C/!!,:$0
This model is used "o s"ore image commen"s or image keywords! The ?4,. forma" suppor"s a single user commen" s"ring, which can be se" using "he FCommentG "ag field name! The 4:. forma" suppor"s as many commen"s as you wan", using any keyword as "he "ag field name! 2ach keyword is sa#ed and loaded "oge"her wi"h "he me"ada"a! The .IF forma" suppor"s as many commen"s as you wan", using any keyword as "he "ag field name! The keyword is no" sa#ed wi"h "he me"ada"a! On loading, each commen" is a""ached "o a "ag key named F3ommen" G where is a number ranging from , "o D:$, where D is "he number of commen"s in "he EIF file!
FI!D-,FIF-M
These models are used "o load 2xif me"ada"a s"ored in J-2E images! The following sub: models are suppor"ed1 FIM062 IF6M(ID This is "he 2xif:TIFF me"ada"a, i!e! "he me"ada"a "ha" are common "o bo"h TIFF and 2xif files! FIM062 IF62 IF This model represen"s 2xif specific me"ada"a! FIM062 IF6E-S This model represen"s 2xif E-S me"ada"a "ha" are par" of "he 2xif s"andard! FIM062 IF6M(I2@DOT2 2xif maker no"es are me"ada"a "ha" are added by camera cons"ruc"ors! There is no public specifica"ion for "hese me"ada"a and each cons"ruc"or uses i"s own specifica"ion "o name "he "ag fields! The following makers are curren"ly suppor"ed by "he library1 (sahi, 3anon, 3asio )"ype $ and "ype +*, Fu&ifilm, Iyocera, Minol"a, Dikon )"ype $, "ype + and "ype >*, Olympus 8 2pson 8 (gfa, -anasonic, -en"ax and Sony! FIM062 IF6IDT2@OThis model represen"s "he 2xif in"eroperabili"y me"ada"a! :ote1 "he 2xif specifica"ions can be downloaded a" "he following 7@L1 h""p188www!exif!org
FI!D-,FIF-+(E
This model s"ore 2xif da"a as a single undecoded raw buffer! FIM0 2 IF6@(W represen"s a single 2xif buffer and is indexed using "he "ag field name F,)if+a>G!
116 (ppendi)
The FIM062 IF6@(W me"ada"a model does no" replace "he o"her 2 IF models! This is an addi"ional me"ada"a used "o s"ore 2xif da"a as a raw binary buffer! Sa#ing 2xif da"a can be #ery complex, bu" sa#ing 2xif raw da"a is Cui"e easy )a" leas" wi"h "he J-2E forma"*! Thus if i" is possible "o preser#e 2xif informa"ion connec"ed wi"h "he J-2E files if such file is e!g! loaded, resiLed "hen sa#ed!
2xif raw loading and sa#ing is suppor"ed by "he J-2E plugin only!
FI!D-I4$C
This model represen"s "he Informa"ion In"erchange Model )IIM*, also called I-T38D(( me"ada"a model, and was originally defined by "he I-T3 and "he Dewspaper (ssocia"ion of (merica )D((* )see h""p188www!ip"c!org8IIM8*! This model was widely used by (dobe -ho"oshop bu" its support is no longer encouraged , nei"her by "he I-T3 nor by (dobe, as i" has been replaced by "he M- s"andard!
(ppendi) 11"
$ag ID ,x,+,, ,x,+,> ,x,+,; ,x,+,P ,x,+,T ,x,+,< ,x,+,( ,x,+,3 ,x,+,F ,x,+$; ,x,+$= ,x,+$? ,x,+$( ,x,+$% ,x,+$2 ,x,++> ,x,++P ,x,++= ,x,++< ,x,++( ,x,++0 ,x,++F ,x,+>+ ,x,+>T ,x,+>3 ,x,+>2 ,x,+>F ,x,+;$ ,x,+;= ,x,+;% ,x,+P, ,x,+P( ,x,+P3 ,x,+PF ,x,+=; ,x,+=P
Jey (pplica"ion@ecord4ersion Ob&ec"Type@eference Ob&ec"(""ribu"e@eference Ob&ec"Dame 2di"S"a"us 2di"orial7pda"e 7rgency Sub&ec"@eference 3a"egory Supplemen"al3a"egories Fix"ureIden"ifier Ieywords 3on"en"Loca"ion3ode 3on"en"Loca"ionDame @elease0a"e @eleaseTime 2xpira"ion0a"e 2xpira"ionTime SpecialIns"ruc"ions (c"ion(d#ised @eferenceSer#ice @eference0a"e @eferenceDumber 0a"e3rea"ed Time3rea"ed 0igi"al3rea"ion0a"e 0igi"al3rea"ionTime Origina"ing-rogram -rogram4ersion Ob&ec"3ycle %y:line 3i"y SubLoca"ion -ro#ince:S"a"e 3oun"ry:-rimaryLoca"ion3ode 3oun"ry:-rimaryLoca"ionDame
Description (pplica"ion @ecord 4ersion )no" edi"able* Ob&ec" Type @eference Ob&ec" (""ribu"e @eference Ti"le 2di" S"a"us 2di"orial 7pda"e 7rgency Sub&ec" @eference 3a"egory Supplemen"al 3a"egoriesA Fix"ure Iden"ifier IeywordsA 3on"en" Loca"ion 3ode 3on"en" Loca"ion Dame @elease 0a"e @elease Time 2xpira"ion 0a"e 2xpira"ion Time Ins"ruc"ions (c"ion (d#ised @eference Ser#ice @eference 0a"e @eference Dumber 0a"e 3rea"ed Time 3rea"ed 0igi"al 3rea"ion 0a"e 0igi"al 3rea"ion Time Origina"ing -rogram -rogram 4ersion Ob&ec" 3ycle (u"hor (u"horQs -osi"ion 3i"y Sub:Loca"ion S"a"e8-ro#ince 3oun"ry 3ode 3oun"ry Dame .eadline 3redi" Source 3opyrigh" Do"ice 3on"ac" 3ap"ion 3ap"ion Wri"er @as"eriLed 3ap"ion Image Type Image Orien"a"ion Language Iden"ifier (udio Type (udio Sampling @a"e (udio Sampling @esolu"ion (udio 0ura"ion (udio Ou"cue Job I0 Mas"er 0ocumen" I0 Shor" 0ocumen" I0 7niCue 0ocumen" I0 Owner I0 Ob&ec" -re#iew File Forma" Ob&ec" -re#iew File 4ersion (udio Ou"cue -ho"oMechanic preferences 3lassify S"a"e Similari"y Index 0ocumen" Do"es 0ocumen" .is"ory 2xif 3amera Info
4hotoshop compatible
: :
: :
: : : : : :
: : : :
: : : : : :
,x,+PP %y:lineTi"le
,x,+=T OriginalTransmission@eference Transmission @eference ,x,+=? .eadline ,x,+=2 3redi" ,x,+T> Source ,x,+T; 3opyrigh"Do"ice ,x,+T= 3on"ac" ,x,+T< 3ap"ion:(bs"rac" ,x,+T( ,x,+T0 ,x,+<+ ,x,+<> ,x,+<T ,x,+?= ,x,+?T ,x,+?< ,x,+?? ,x,+?( ,x,+%< ,x,+%? ,x,+%( ,x,+%% ,x,+%3 ,x,+3< ,x,+3? ,x,+3( ,x,+00 ,x,+2$ ,x,+2; ,x,+2= ,x,+2T ,x,+2< Wri"er:2di"or @as"eriLed3ap"ion ImageType ImageOrien"a"ion LanguageIden"ifier (udioType (udioSampling@a"e (udioSampling@esolu"ion (udio0ura"ion (udioOu"cue JobI0 Mas"er0ocumen"I0 Shor"0ocumen"I0 7niCue0ocumen"I0 OwnerI0 Ob&ec"-re#iewFileForma" Ob&ec"-re#iewFile4ersion Ob&ec"-re#iew0a"a -refs 3lassifyS"a"e Similari"yIndex 0ocumen"Do"es 0ocumen".is"ory 2xif3ameraInfo

: : : : : : : : : : : : : : : : : : : : : : :
A semicolon separa"ed lis" of words Legend* yes 1 no 1 :
$able 1=* List of tag %eys supported by the I4$C metadata model.
11& (ppendi)
FI!D-F!4
FIM0 M- represen"s a single (dobe FF!L4ac%etG! ML packe" and is indexed using "he "ag field name
The (dobe M- s"andard is described a" "he following 7@L1 h""p188www!adobe!com8produc"s8xmp8main!h"ml
FI!D-.,/$IFF
This model represen"s "he EeoTIFF me"ada"a s"andard and is used "o add georeferencing informa"ion "o TIFF files! The EeoTIFF specifica"ions can be found a" "he following 7@L1 h""p188www!remo"esensing!org8geo"iff8geo"iff!h"ml
FI!D-(:I!($I/:
This model is used "o load and sa#e anima"ion me"ada"a a""ached "o an anima"ed EIF or MDE file! Me"ada"a suppor"ed by "he FIM06(DIM(TIOD model ha#e been defined by FreeImage! 3urren"ly, "his model is only suppor"ed by "he EIF plugin! The FIM06(DIM(TIOD specifica"ions are described la"er in "his appendix!
FI!D-C90$/!
FIM0637STOM is a placeholder me"ada"a model "ha" can be used "o s"ore user specific me"ada"a! I" can be used for example "o s"ore me"ada"a "ha" would be used by a cus"om plugin wri""en by you!
(ppendi) 11=
FI!D-(:I!($I/: metadata model specification

The (nima"ion me"ada"a model is a generic model used "o load and sa#e anima"ion me"ada"a a""ached "o an anima"ed file )such as a EIF or a MDE file*! Me"ada"a suppor"ed by "his model ha#e been defined specifically for "he FreeImage library )"his is no" a me"ada"a s"andard such as 2xif*! When sa#ing anima"ion me"ada"a "o an anima"ed file, "he FreeImage me"ada"a are "ransparen"ly "ransla"ed "o "he me"ada"a reCuired by a gi#en plugin specifica"ion! On "he o"her hand, when loading an anima"ed file, i"s anima"ion me"ada"a are "ransparen"ly "ransla"ed "o "he FreeImage anima"ion me"ada"a model! 3urren"ly, "his model is only suppor"ed by "he EIF plugin! The following me"ada"a are suppor"ed by "he model! $ags relating to a single page or relating to page # of a multipage animated file
$ag :ame
Field :ame Dec
$ag ID <e) ,x,,,$ ,x,,,+ ,x,,,> ,x,,,;
$ype
Count
Logical wid"h Logical heigh" Elobal pale""e Loop
LogicalWid"h Logical.eigh" Elobal-ale""e Loop
$ + > ;
FI0T6S.O@T FI0T6S.O@T FI0T6-(L2TT2 FI0T6LODE
$ $ (ny $
$ags relating to each page 1including page #2 of a single page or a multipage animated file $ag :ame Field :ame Dec Frame lef" Frame "op Do local pale""e In"erlaced Frame "ime Frame disposal me"hod FrameLef" FrameTop DoLocal-ale""e In"erlaced FrameTime 0isposalMe"hod ;,?T ;,?< ;,?? ;$,, ;$,$ ;$,+ $ag ID <e) ,x$,,$ ,x$,,+ ,x$,,> ,x$,,; ,x$,,P ,x$,,= FI0T6S.O@T FI0T6S.O@T FI0T6%BT2 FI0T6%BT2 FI0T6LODE FI0T6%BT2 $ $ $ $ $ $ $ype Count
1'# (ppendi)
:ote* The following #alues are suppor"ed by "he Disposal!ethod "ag1 EIF60IS-OS(L67DS-23IFI20 EIF60IS-OS(L6L2(42 EIF60IS-OS(L6%(3IE@O7D0 EIF60IS-OS(L6-@24IO7S S, S$ S+ S>
$ags relating to a single page or relating to page # of a multipage animated file

LogicalEidth Wid"h of en"ire can#as area "ha" each page is displayed in ,:=PP>P Tag Type S S $ ),,,$!.* FI0T6S.O@T $
3oun" S
Sa#e 0efaul" S dibQs wid"h Load1 always exis"s in file and se" Logical<eight .eigh" of en"ire can#as area "ha" each page is displayed in ,:=PP>P Tag Type S S + ),,,+!.* FI0T6S.O@T $
3oun" S
Sa#e 0efaul" S dibQs heigh" Load1 always exis"s in file and se" .lobal4alette @E%X7(0 da"a for a 5global5 pale""e which can apply "o all images wi"h no local pale""e up "o +P= x FI0T6-(L2TT2 Tag Type S S > ),,,>!.* FI0T6-(L2TT2 , "o +P=
3oun" S
Sa#e 0efaul" S no global pale""e Sa#e Do"es1 rounded down "o "he neares" power of + en"ries Load1 se" if exis"s in file, no" se" if "he file has no global pale""e (ddi"ional no"es )EIF specific* The pale""e siLe mus" be +, ;, <, $=, >+, =;, $+< or +P=, or no global pale""e ),*! If you specify a me"ada"a wi"h coun" $+T, only "he firs" =; will be used, since i" rounds down, and "he plugin will se" "he global pale""e siLe in "he EIF header "o be = bi"s! Loop The number of "imes "he anima"ion should be played ,:=PP>= ),Sinfini"e* Tag1 Type1 ; ),,,;!.* FI0T6LODE
3oun"1 $
(ppendi) 1'1
Sa#e 0efaul" S , )infini"e loops* Sa#e Do"es1 For EIFs specifically, "he D2TS3(-2+!, applica"ion ex"ension represen"s "he number of "imes "o repea" "he anima"ion, "hus, $ repea" means + loops )play "hru "he anima"ion "wice*, =PP>P repea"s is "he larges" #alue which can be s"ored, and "ransla"es "o =PP>= loops! Load1 "he me"ada"a is always se" "o a #alue ,:=PP>= )se" "o , or +:=PP>= if "he ex"ension is in "he file, $ if "he ex"ension is no" in "he file*
$ags relating to each page 1including page #2 of a single page or a multipage animated file
FrameLeft The x offse" in "he logical can#as area "o display "he image! ),:=PP>P* Tag Type S S ;,?T )$,,$!.* FI0T6S.O@T $
3oun" S
Sa#e 0efaul" S , Load1 always exis"s in file and se" Frame$op The y offse" in "he logical can#as area "o display "he image! ),:=PP>P* Tag Type S S ;,?< )$,,+!.* FI0T6S.O@T $
3oun" S
Sa#e 0efaul" S , Load1 always exis"s in file and se" :oLocal4alette ( flag "o supress sa#ing "he dibQs a""ached pale""e )making i" use "he global pale""e*! The local pale""e is "he pale""e used by a page! This pale""e da"a is no" se" #ia me"ada"a )like "he global pale""e* as i" is a""ached "o "he dib! Tag Type S S ;,?? )$,,>!.* FI0T6%BT2 $
3oun" S
Sa#e 0efaul" S , )meaning, yes, sa#e "he local pale""e da"a* Load1 always exis"s in file and se" Interlaced Tells if "he image should be s"ored in"erlaced Tag Type S S ;$,, )$,,;!.* FI0T6%BT2 $
3oun" S
Sa#e 0efaul" S , Load1 always exis"s in file and se" Frame$ime
1'' (ppendi)
The amoun" of "ime in ms "o display "he frame for )EIF specific : "he #alue s"ored in "he file is cen"iseconds )$8$,,"h of a second**! Tag Type S S ;$,$ )$,,P!.* FI0T6LODE $
3oun" S Sa#e Do"es1
Sa#e 0efaul" S $,,ms )EIF specific : "he #alue s"ored is $,cs* For EIF, "he #alue specified in ms is rounded down, such as $+?ms is s"ored as $+cs! I2P8I2= ha#e a minimum and defaul" of $,,ms! MoLilla8Firefox8De"scape =98Opera ha#e a minimum of +,ms and a defaul" of $,,ms if less "han +,ms is specified or "he E32 is absen"! De"scape ; has a minimum of $,ms if ,ms is specified, bu" will use ,ms if "he E32 is absen"! The EIF plugin always wri"es a E32 ex"ension "o "he EIF file, and i" also always uses EIF<?a! Load1 always se", se" "o , if does no" exis" in file Disposal!ethod Wha" "o do wi"h "he logical can#as area af"er displaying "his image! Tag Type S S ;$,+ )$,,=!.* FI0T6%BT2 $
3oun" S
Sa#e 0efaul" S EIF60IS-OS(L6%(3IE@O7D0 )res"ore "o "he background color, which is "ransparen" wi"h , alpha* Sa#e Do"es1 EIF60IS-OS(L67DS-23IFI20 probably &us" EIF60IS-OS(L6L2(42 and should no" be used! does "he same as
EIF60IS-OS(L6L2(42 will lea#e "he image in place "o be en"irely or par"ially o#erdrawn by "he nex" image! EIF60IS-OS(L6%(3IE@O7D0 will blank ou" "he area used by "he frame wi"h "he background color! EIF60IS-OS(L6-@24IO7S will re"urn "he logical can#as "o "he pre#ious s"a"e before "he image was drawn! Load1 always se", se" "o EIF60IS-OS(L6L2(42 if does no" exis" in file
(dditional notes 1.IF specific2

Transparency is suppor"ed indi#idually for all pages, "he firs" en"irely "ransparen" index in "he "able is used, "he res" of "he "able will be en"irely opaCue! The background color is only se" and s"ored for page ,, bu" reCuires "ha" "he global pale""e be se" in order "o use i" properly! The .IF-4L(3 (CJ load flag op"ion )see Table >* will load a single page as a >+bpp image wi"h "ransparency by displaying each page from , up "o "he specified page, obeying "he "ransparency o#erlaying and gif disposal me"hods! Do"e "ha" i" does no" ac"ually play "he image anima"ion in a displayable way! I" 5plays5 "he image in"ernally from page , "o "he page reCues"ed, re"urning a single s"ill image of wha" "ha" frame would really look like! Do"e "ha" EIF6-L(B%(3I will re"urn a >+bpp image1 since each indi#idual frame may con"ain i"s own pale""e and "ransparency, a single frame of an anima"ed EIF, when composi"ed o#er "op of "he pre#ious frame, may con"ain more "han +P= colors "o"al! I" may no" be possible "o ex"rac" each frame and sa#e "hem as a EIF if you wan" each s"ill frame "o look like i" would look like in a web browser for example! Mos" EIF anima"ion programs will 5op"imiLe5 "he EIF by making each indi#idual frame con"ain lo"s of "ransparency for
(ppendi) 1'3
where "he pixels ma"ched "he pre#ious frame, so if you &us" ex"rac" "he frames normally and sa#e "hem as EIF files, e#ery"hing bu" "he firs" frame may look like a bunch of random fuLL pixels! The .IF-L/(D'56 load flag op"ion is used in"ernally by EIF6-L(B%(3I, bu" can be used by users as well, i" &us" pre#en"s a lo" of bi"shif"ing and annoying "hings "ha" come wi"h + and $= color images! 7sing "he FIM06(DIM(TIOD me"ada"a model This model is useful for genera"ing anima"ed EIFs wi"h FreeImage, which web browsers will la"er be displaying! The me"ada"a is used "o sa#e )and load* "he #arious op"ions "ha" EIF files suppor" for defining an anima"ion! The simples" of examples would no" need "o change any me"ada"a! Jus" open a mul"ipage EIF wi"h crea"e6newST@72 and s"ar" adding pages "o i"! The EIF genera"ed when you close "he mul"ipage image will loop fore#er, and display each page for $8$, of a second )$,,ms*! 2ach page of "he EIF will ha#e i"s own pale""e and fill "he en"ire logical area! The wors" snag a user could run in"o is adding pages "o "he mul"ipage bi"map which are larger "han "he firs" page "hey added, because wi"hou" se""ing specific me"ada"a, "he logical can#as area will be se" "o "he same siLe of "he firs" page, and i" is undefined )no" allowed* by "he EIF specifica"ion "echnically if you ha#e a frame ex"end ou"side "he can#as area! )I28Firefox will simply make "he image larger as needed for "he larges" frame, Opera will chop off any por"ion of "he image "ha" is ou"side "he logical area*!
++ assume ;e &ave an array o* di-s ;&ic& are already B-pp and all t&e same siLe0 ++ and some *loat called *ps *or *rames per second FI)!L"IBI")AP 'multi 5 FreeImage_Open)ultiBitmap(FIF_(IF0 2outputGgi*20 "/! 0 FAL# $% D7O/D d;Frame"ime 5 (D7O/D$((C===G=* + *ps$ O =GE*$% *or(int i 5 =% i N C=% iOO $ 1 ++ clear any animation metadata used -y t&is di- as ;eKll adding our o;n ones FreeImage_#et)etadata(FI)D_ANI)A"ION0 di-PiQ0 N!LL0 N!LL$% ++ add animation tags to di-PiQ FI"A( 'tag 5 FreeImage_Create"ag($% i*(tag$ 1 FreeImage_#et"ag6ey(tag0 2Frame"ime2$% FreeImage_#et"ag"ype(tag0 FID"_LON($% FreeImage_#et"agCount(tag0 C$% FreeImage_#et"agLengt&(tag0 @$% FreeImage_#et"agValue(tag0 Id;Frame"ime$% FreeImage_#et)etadata(FI)D_ANI)A"ION0 di-PiQ0 FreeImage_(et"ag6ey(tag$0 tag$% F!eeI"age_Delete-ag(tag*; 9 FreeImage_AppendPage(multi0 di-PiQ$% 9 FreeImage_Close)ultiBitmap(multi$%
1'5 (ppendi)
(ppendi) 1'5

Free Image 3151

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Free Image 3151

Încărcat de

Drepturi de autor:

Formate disponibile

FreeImage

a free, open source graphics library

Documentation Library version 3.15.1

itmap function reference

!etadata function reference

$ool%it function reference

FreeImage 3.15.1 documentation

"1 "' &5 &6 &= 1#1 1#'

FreeImage 3.15.1 documentation

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

FreeImage 3.15.1 documentation

FreeImage does no" suppor"1

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

itmap function reference

FreeImage 3.15.1 documentation

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

FreeImage 3.15.1 documentation

itmap management functions

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

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

I3O6M(I2(L-.( J-2E602F(7LT J-2E6F(ST J-2E6(337@(T2 J-2E63MBI

$able 3* /ptionnal decoder constants.

FreeImage 3.15.1 documentation

pointer to not needed pointer to pointer to

'* 5 *open(Fmy-itmapG-mpH0 Fr-H$%

FreeImage 3.15.1 documentation

J+I J-+ J-2E

FreeImage 3.15.1 documentation

-DM602F(7LT -DM6S(426@(W -DM6S(426(S3II

$able 5* /ptionnal encoder constants.

FreeImage 3.15.1 documentation

'* 5 *open(Fmy-itmapG-mpH0 F;-H$%

i* (FreeImage_#ave"o.andle(FIF_B)P0 -itmap0 Iio0 (*i_&andle$*0 =$$ 1 ++ -itmap success*ully saved4 9 *close(*$%

0ele"es a pre#iously loaded FI%ITM(- from memory!

FreeImage 3.15.1 documentation

itmap information functions

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

@e"urns "he wid"h of "he bi"map in pixel uni"s!

@e"urns "he heigh" of "he bi"map in pixel uni"s!

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

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

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

4i)el access functions

2ach forma" has "he following specifics1

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

-itsPVQGgreen 5 C?B% -itsPVQG-lue 5 C?B%

FreeImage 3.15.1 documentation

FreeImage 3.15.1 documentation

i* (FreeImage_#ave"o.andle(FIF_B)P0 -itmap0 Iio0 (i_&andle$0 =$$ 1 ++ -itmap successully saved4 9 close(*$%

I* (proileTWdata$ 1 ++ proile data present 9

++ determine0 ;&et&er proile support is present i (FreeImage_FIF#upportsICCProiles(FIF_"IFF$$ 1 ++ proile support present 9

++ Close t&e src stream close(ile$% 9 9 return -#uccess%

++ Close t&e src stream close(src_ile$% 9 9 return -#uccess%

_I)A( _FO/)A" i0 c&ar 'input0 c&ar 'output0 int output_*lag$