emotion/ratio - Explain how to use emotion_object_ratio_get().

git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/emotion@62068 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33

diff --git a/doc/img/emotion_ratio.eps b/doc/img/emotion_ratio.eps
new file mode 100644 (file)
index 0000000..636cc8d
--- /dev/null
+++ b/doc/img/emotion_ratio.eps
@@ -0,0 +1,308 @@
+%!PS-Adobe-3.0 EPSF-3.0
+%%Creator: cairo 1.10.2 (http://cairographics.org)
+%%CreationDate: Wed Aug  3 20:45:05 2011
+%%Pages: 1
+%%BoundingBox: 0 -1 558 166
+%%DocumentData: Clean7Bit
+%%LanguageLevel: 2
+%%EndComments
+%%BeginProlog
+/cairo_eps_state save def
+/dict_count countdictstack def
+/op_count count 1 sub def
+userdict begin
+/q { gsave } bind def
+/Q { grestore } bind def
+/cm { 6 array astore concat } bind def
+/w { setlinewidth } bind def
+/J { setlinecap } bind def
+/j { setlinejoin } bind def
+/M { setmiterlimit } bind def
+/d { setdash } bind def
+/m { moveto } bind def
+/l { lineto } bind def
+/c { curveto } bind def
+/h { closepath } bind def
+/re { exch dup neg 3 1 roll 5 3 roll moveto 0 rlineto
+      0 exch rlineto 0 rlineto closepath } bind def
+/S { stroke } bind def
+/f { fill } bind def
+/f* { eofill } bind def
+/n { newpath } bind def
+/W { clip } bind def
+/W* { eoclip } bind def
+/BT { } bind def
+/ET { } bind def
+/pdfmark where { pop globaldict /?pdfmark /exec load put }
+    { globaldict begin /?pdfmark /pop load def /pdfmark
+    /cleartomark load def end } ifelse
+/BDC { mark 3 1 roll /BDC pdfmark } bind def
+/EMC { mark /EMC pdfmark } bind def
+/cairo_store_point { /cairo_point_y exch def /cairo_point_x exch def } def
+/Tj { show currentpoint cairo_store_point } bind def
+/TJ {
+  {
+    dup
+    type /stringtype eq
+    { show } { -0.001 mul 0 cairo_font_matrix dtransform rmoveto } ifelse
+  } forall
+  currentpoint cairo_store_point
+} bind def
+/cairo_selectfont { cairo_font_matrix aload pop pop pop 0 0 6 array astore
+    cairo_font exch selectfont cairo_point_x cairo_point_y moveto } bind def
+/Tf { pop /cairo_font exch def /cairo_font_matrix where
+      { pop cairo_selectfont } if } bind def
+/Td { matrix translate cairo_font_matrix matrix concatmatrix dup
+      /cairo_font_matrix exch def dup 4 get exch 5 get cairo_store_point
+      /cairo_font where { pop cairo_selectfont } if } bind def
+/Tm { 2 copy 8 2 roll 6 array astore /cairo_font_matrix exch def
+      cairo_store_point /cairo_font where { pop cairo_selectfont } if } bind def
+/g { setgray } bind def
+/rg { setrgbcolor } bind def
+/d1 { setcachedevice } bind def
+%%EndProlog
+11 dict begin
+/FontType 42 def
+/FontName /DejaVuSans def
+/PaintType 0 def
+/FontMatrix [ 1 0 0 1 0 0 ] def
+/FontBBox [ 0 0 0 0 ] def
+/Encoding 256 array def
+0 1 255 { Encoding exch /.notdef put } for
+Encoding 1 /uni0056 put
+Encoding 2 /uni0049 put
+Encoding 3 /uni0044 put
+Encoding 4 /uni0045 put
+Encoding 5 /uni004F put
+Encoding 6 /uni0046 put
+Encoding 7 /uni0054 put
+Encoding 8 /uni004C put
+Encoding 9 /uni0053 put
+Encoding 10 /uni0052 put
+Encoding 11 /uni0043 put
+Encoding 12 /uni0048 put
+/CharStrings 13 dict dup begin
+/.notdef 0 def
+/uni0056 1 def
+/uni0049 2 def
+/uni0044 3 def
+/uni0045 4 def
+/uni004F 5 def
+/uni0046 6 def
+/uni0054 7 def
+/uni004C 8 def
+/uni0053 9 def
+/uni0052 10 def
+/uni0043 11 def
+/uni0048 12 def
+end readonly def
+/sfnts [
+<00010000000a008000030020636d61700043f0c90000078c000000586376742000691d390000
+07e4000001fe6670676d7134766a000009e4000000ab676c7966be3a60b5000000ac000006e0
+68656164f5a8919600000a9000000036686865610cb8065e00000ac800000024686d74784255
+075c00000aec000000346c6f636100002cb400000b20000000386d617870047a067100000b58
+00000020707265703b07f10000000b780000056800020066fe96046605a400030007001a400c
+04fb0006fb0108057f0204002fc4d4ec310010d4ecd4ec301311211125211121660400fc7303
+1bfce5fe96070ef8f2720629000100100000056805d5000600b7402704110506050311020306
+060503110403000100021101010042030401af0006040302000505010710d4c4173931002fec
+3239304b5358071005ed071008ed071008ed071005ed5922b2500801015d406200032a034704
+47055a037d038303070600070208040906150114021a041a052a002601260229042905250620
+083800330133023c043c053706480045014502490449054706590056066602690469057a0076
+017602790479057506800898009706295d005d21013309013301024afdc6d301d901dad2fdc7
+05d5fb1704e9fa2b000100c90000019305d50003002eb700af02011c00040410fc4bb0105458
+b9000000403859ec31002fec3001400d30054005500560058f059f05065d13331123c9caca05
+d5fa2b00000200c9000005b005d500080011002e4015009509810195100802100a0005190d32
+001c09041210fcecf4ec113939393931002fecf4ec30b2601301015d01113320001110002125
+21200011100029010193f40135011ffee1fecbfe42019f01b20196fe68fe50fe61052ffb7701
+18012e012c0117a6fe97fe80fe7efe960000000100c90000048b05d5000b002e401506950402
+950081089504ad0a05010907031c00040c10fcec32d4c4c431002fececf4ec10ee30b21f0d01
+015d132115211121152111211521c903b0fd1a02c7fd3902f8fc3e05d5aafe46aafde3aa0000
+00020073ffe305d905f0000b00170023401306951200950c91128c1809190f33031915101810
+fcecfcec310010e4f4ec10ee3001220011100033320011100027200011100021200011100003
+27dcfefd0103dcdc0101feffdc013a0178fe88fec6fec5fe870179054cfeb8fee5fee6feb801
+48011a011b0148a4fe5bfe9efe9ffe5b01a40162016201a50000000100c90000042305d50009
+002940120695040295008104ad08050107031c00040a10fcec32d4c431002fecf4ec10ee30b2
+0f0b01015d13211521112115211123c9035afd700250fdb0ca05d5aafe48aafd37000001fffa
+000004e905d50007004a400e0602950081040140031c0040050810d4e4fce431002ff4ec3230
+014bb00a5458bd00080040000100080008ffc03811373859401300091f00100110021f071009
+400970099f09095d03211521112311210604effdeecbfdee05d5aafad5052b00000100c90000
+046a05d500050025400c0295008104011c033a00040610fcecec31002fe4ec30400930075007
+8003800404015d133311211521c9ca02d7fc5f05d5fad5aa00010087ffe304a205f00027007e
+403c0d0c020e0b021e1f1e080902070a021f1f1e420a0b1e1f0415010015a114941895110495
+00942591118c281e0a0b1f1b0700221b190e2d071914222810dcc4ecfcece411123939393931
+0010e4f4e4ec10eef6ee10c6111739304b535807100eed11173907100eed1117395922b20f29
+01015db61f292f294f29035d01152e012322061514161f011e0115140421222627351e013332
+363534262f012e01353424333216044873cc5fa5b377a67ae2d7feddfee76aef807bec72adbc
+879a7be2ca0117f569da05a4c53736807663651f192bd9b6d9e0302fd04546887e6e7c1f182d
+c0abc6e42600000200c90000055405d50013001c00b14035090807030a061103040305110404
+034206040015030415950914950d810b040506031109001c160e050a191904113f140a1c0c04
+1d10fcec32fcc4ec1117391139393931002f3cf4ecd4ec123912391239304b5358071005ed07
+1005ed1117395922b2401e01015d40427a130105000501050206030704150015011402160317
+0425002501250226032706260726082609201e36013602460146026805750475057713880688
+07980698071f5d005d011e01171323032e012b01112311212016151406011133323635342623
+038d417b3ecdd9bf4a8b78dcca01c80100fc83fd89fe9295959202bc16907efe68017f9662fd
+8905d5d6d88dba024ffdee878383850000010073ffe3052705f000190036401a0da10eae0a95
+1101a100ae04951791118c1a07190d003014101a10fcec32ec310010e4f4ecf4ec10eef6ee30
+b40f1b1f1b02015d01152e0123200011100021323637150e01232000111000213216052766e7
+82ff00fef00110010082e7666aed84feadfe7a0186015386ed0562d55f5efec7fed8fed9fec7
+5e5fd34848019f01670168019f470000000100c90000053b05d5000b002c4014089502ad0400
+810a0607031c053809011c00040c10fcec32fcec3231002f3ce432fcec30b2500d01015d1333
+11211133112311211123c9ca02decacafd22ca05d5fd9c0264fa2b02c7fd3900000000020003
+00000000001400010000000000340004002000000004000400010000f00cffff0000f000ffff
+10000001000000000006002400000000000d0000000100020003000400050006000700080009
+000a000b000c013500b800cb00cb00c100aa009c01a600b800660000007100cb00a002b20085
+007500b800c301cb0189022d00cb00a600f000d300aa008700cb03aa0400014a003300cb0000
+00d9050200f4015400b4009c01390114013907060400044e04b4045204b804e704cd00370473
+04cd04600473013303a2055605a60556053903c5021200c9001f00b801df007300ba03e90333
+03bc0444040e00df03cd03aa00e503aa0404000000cb008f00a4007b00b80014016f007f027b
+0252008f00c705cd009a009a006f00cb00cd019e01d300f000ba018300d5009803040248009e
+01d500c100cb00f600830354027f00000333026600d300c700a400cd008f009a0073040005d5
+010a00fe022b00a400b4009c00000062009c0000001d032d05d505d505d505f0007f007b0054
+00a406b80614072301d300b800cb00a601c301ec069300a000d3035c037103db0185042304a8
+0448008f0139011401390360008f05d5019a0614072306660179046004600460047b009c0000
+0277046001aa00e904600762007b00c5007f027b000000b4025205cd006600bc006600770610
+00cd013b01850389008f007b0000001d00cd074a042f009c009c0000077d006f0000006f0335
+006a006f007b00ae00b2002d0396008f027b00f600830354063705f6008f009c04e10266008f
+018d02f600cd03440029006604ee00730000140000960000b707060504030201002c2010b002
+254964b040515820c859212d2cb002254964b040515820c859212d2c20100720b00050b00d79
+20b8ffff5058041b0559b0051cb0032508b0042523e120b00050b00d7920b8ffff5058041b05
+59b0051cb0032508e12d2c4b505820b0fd454459212d2cb002254560442d2c4b5358b00225b0
+022545445921212d2c45442d2cb00225b0022549b00525b005254960b0206368208a108a233a
+8a10653a2d0000010000000251eb30bbbeaa5f0f3cf5001f080000000000c896fa5500000000
+c896fa55f7d6fcae0d72095500000008000000010000000000010000076dfe1d00000de2f7d6
+fa510d7200010000000000000000000000000000000d04cd006605790010025c00c9062900c9
+050e00c9064c0073049a00c904e3fffa047500c905140087058f00c905960073060400c90000
+000000000044000001240000016c000001ec0000024c000002d80000032c0000039c000003e0
+000004d8000005ec00000684000006e000010000000d0354002b0068000c0002001000990008
+00000415021600080004b8028040fffbfe03fa1403f92503f83203f79603f60e03f5fe03f4fe
+03f32503f20e03f19603f02503ef8a4105effe03ee9603ed9603ecfa03ebfa03eafe03e93a03
+e84203e7fe03e63203e5e45305e59603e48a4105e45303e3e22f05e3fa03e22f03e1fe03e0fe
+03df3203de1403dd9603dcfe03db1203da7d03d9bb03d8fe03d68a4105d67d03d5d44705d57d
+03d44703d3d21b05d3fe03d21b03d1fe03d0fe03cffe03cefe03cd9603cccb1e05ccfe03cb1e
+03ca3203c9fe03c6851105c61c03c51603c4fe03c3fe03c2fe03c1fe03c0fe03bffe03befe03
+bdfe03bcfe03bbfe03ba1103b9862505b9fe03b8b7bb05b8fe03b7b65d05b7bb03b78004b6b5
+2505b65d40ff03b64004b52503b4fe03b39603b2fe03b1fe03b0fe03affe03ae6403ad0e03ac
+ab2505ac6403abaa1205ab2503aa1203a98a4105a9fa03a8fe03a7fe03a6fe03a51203a4fe03
+a3a20e05a33203a20e03a16403a08a4105a096039ffe039e9d0c059efe039d0c039c9b19059c
+64039b9a10059b19039a1003990a0398fe0397960d0597fe03960d03958a410595960394930e
+05942803930e0392fa039190bb0591fe03908f5d0590bb039080048f8e25058f5d038f40048e
+25038dfe038c8b2e058cfe038b2e038a8625058a410389880b05891403880b03878625058764
+038685110586250385110384fe038382110583fe0382110381fe0380fe037ffe0340ff7e7d7d
+057efe037d7d037c64037b5415057b25037afe0379fe03780e03770c03760a0375fe0374fa03
+73fa0372fa0371fa0370fe036ffe036efe036c21036bfe036a1142056a530369fe03687d0367
+11420566fe0365fe0364fe0363fe0362fe03613a0360fa035e0c035dfe035bfe035afe035958
+0a0559fa03580a035716190557320356fe035554150555420354150353011005531803521403
+514a130551fe03500b034ffe034e4d10054efe034d10034cfe034b4a13054bfe034a4910054a
+1303491d0d05491003480d0347fe0346960345960344fe0343022d0543fa0342bb03414b0340
+fe033ffe033e3d12053e14033d3c0f053d12033c3b0d053c40ff0f033b0d033afe0339fe0338
+37140538fa033736100537140336350b05361003350b03341e03330d0332310b0532fe03310b
+03302f0b05300d032f0b032e2d09052e10032d09032c32032b2a25052b64032a2912052a2503
+2912032827250528410327250326250b05260f03250b0324fe0323fe03220f03210110052112
+032064031ffa031e1d0d051e64031d0d031c1142051cfe031bfa031a42031911420519fe0318
+64031716190517fe031601100516190315fe0314fe0313fe031211420512fe0311022d051142
+03107d030f64030efe030d0c16050dfe030c0110050c16030bfe030a100309fe0308022d0508
+fe030714030664030401100504fe03401503022d0503fe0302011005022d0301100300fe0301
+b80164858d012b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b
+2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b
+2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b
+2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b
+2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b002b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b
+2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b
+2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b
+2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b
+2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b1d00>
+] def
+/f-0-0 currentdict end definefont pop
+%%Page: 1 1
+%%BeginPageSetup
+%%PageBoundingBox: 0 -1 558 166
+%%EndPageSetup
+q 0 -1 558 167 rectclip q
+0 165.637 558 -166 re W n
+0 g
+0.8 w
+0 J
+0 j
+[] 0.0 d
+4 M q 1 0 0 -1 0 165.636871 cm
+0.398 0.406 127.203 127.199 re S Q
+0.8 g
+0.398 137.231 127.203 -71.199 re f
+0 g
+0.8 w
+q 1 0 0 -1 0 165.636871 cm
+0.398 28.406 127.203 71.199 re S Q
+BT
+25.6 0 0 25.6 24.068512 92.31148 Tm
+/f-0-0 1 Tf
+<0102030405>Tj
+ET
+Q q
+204.039 165.231 127.199 -127.199 re W n
+q
+204 165.637 128 -128 re W n
+[ 1 0 0 1 -0.000000000000003553 -0.363129 ] concat
+  q
+Q q
+0.8 g
+154.57 165.281 226.133 -126.578 re f
+0 g
+0.8 w
+0 J
+0 j
+[] 0.0 d
+4 M q 1 0 0 -1 0 166 cm
+154.57 0.719 226.133 126.578 re S Q
+BT
+45.511112 0 0 45.511112 196.648634 85.426692 Tm
+/f-0-0 1 Tf
+<0102030405>Tj
+ET
+  Q
+Q
+0 g
+1.4224 w
+0 J
+0 j
+[ 5.6896 5.6896] 0 d
+4 M q 1 0 0 -1 0 165.636871 cm
+154.57 0.719 226.133 126.578 re S Q
+0.8 w
+[] 0.0 d
+q 1 0 0 -1 0 165.636871 cm
+204.039 0.406 127.199 127.199 re S Q
+q 1 0 0 -1 0 165.636871 cm
+429.754 0.406 127.199 127.199 re S Q
+0.8 g
+429.754 164.961 127.199 -126.816 re f
+0 g
+1.06768 w
+q 0.561432 0 0 -1 0 165.636871 cm
+765.46 0.676 226.562 126.816 re S Q
+BT
+25.6 0 0 45.597663 453.422949 84.954295 Tm
+/f-0-0 1 Tf
+<0102030405>Tj
+ET
+BT
+12.8 0 0 12.8 53.868512 0.00000663977 Tm
+/f-0-0 1 Tf
+<060207>Tj
+ET
+BT
+12.8 0 0 12.8 254.340662 0.808112 Tm
+/f-0-0 1 Tf
+<06020808>Tj
+ET
+BT
+12.8 0 0 12.8 464.260437 7.273102 Tm
+/f-0-0 1 Tf
+[<09070a>-1<04>-1<07>58<0b>-1<0c>]TJ
+ET
+Q Q
+showpage
+%%Trailer
+count op_count sub {pop} repeat
+countdictstack dict_count sub {end} repeat
+cairo_eps_state restore
+%%EOF

diff --git a/doc/img/emotion_ratio.png b/doc/img/emotion_ratio.png
new file mode 100644 (file)
index 0000000..4ae37fd
Binary files /dev/null and b/doc/img/emotion_ratio.png differ

diff --git a/src/lib/Emotion.h b/src/lib/Emotion.h
index 198f26a..cfe27b7 100644 (file)
--- a/src/lib/Emotion.h
+++ b/src/lib/Emotion.h
@@ -552,6 +552,66 @@ EAPI Eina_Bool    emotion_object_audio_handled_get     (const Evas_Object *obj);
  * so the aspect won't be changed (by wrongly resizing the object). Or to crop
  * the video correctly, if necessary.
  *
+ * The described behavior can be applied like following. Consider a given
+ * emotion object that we want to position inside an area, which we will
+ * represent by @c w and @c h. Since we want to position this object either
+ * stretching, or filling the entire area but overflowing the video, or just
+ * adjust the video to fit inside the area without keeping the aspect ratio, we
+ * must compare the video aspect ratio with the area aspect ratio:
+ * @code
+ * int w = 200, h = 300; // an arbitrary value which represents the area where
+ *                       // the video would be placed
+ * int vw, vh;
+ * double r, vr = emotion_object_ratio_get(obj);
+ * r = (double)w / h;
+ * @endcode
+ *
+ * Now, if we want to make the video fit inside the area, the following code
+ * would do it:
+ * @code
+ * if (vr > r) // the video is wider than the area
+ *   {
+ *      vw = w;
+ *      vh = w / vr;
+ *   }
+ * else // the video is taller than the area
+ *   {
+ *      vh = h;
+ *      vw = h * vr;
+ *   }
+ * evas_object_resize(obj, vw, vh);
+ * @endcode
+ *
+ * And for keeping the aspect ratio but making the video fill the entire area,
+ * overflowing the content which can't fit inside it, we would do:
+ * @code
+ * if (vr > r) // the video is wider than the area
+ *   {
+ *      vh = h;
+ *      vw = h * vr;
+ *   }
+ * else // the video is taller than the area
+ *   {
+ *      vw = w;
+ *      vh = w / vr;
+ *   }
+ * evas_object_resize(obj, vw, vh);
+ * @endcode
+ *
+ * Finally, by just resizing the video to the video area, we would have the
+ * video stretched:
+ * @code
+ * vw = w;
+ * vh = h;
+ * evas_object_resize(obj, vw, vh);
+ * @endcode
+ *
+ * The following diagram exemplifies what would happen to the video,
+ * respectively, in each case:
+ *
+ * @image html emotion_ratio.png
+ * @image latex emotion_ratio.eps width=\textwidth
+ *
  * @note This function returns the aspect ratio that the video @b should be, but
  * sometimes the reported size from emotion_object_size_get() represents a
  * different aspect ratio. You can safely resize the video to respect the aspect