January 2014 updates to Magnum

Since the pre­vi­ous Oc­to­ber snap­shot Mag­num gained Vis­ual Stu­dio port, font con­ver­sion util­i­ty, im­proved text ren­der­ing along with ex­am­ple ap­pli­ca­tion, sup­port for OpenGL de­bug out­put, doc­u­men­ta­tion up­dates, bet­ter test cov­er­age and many more us­abil­i­ty im­prove­ments and fix­es.

The Jan­u­ary snap­shot is avail­able un­der snapshot-2014-01 tag in Cor­rade, Mag­num, Mag­num Plug­ins and Mag­num In­te­gra­tion GitHub repos­i­to­ries. This ar­ti­cle will de­scribe the most im­por­tant changes, for all the com­mits that went to mas­ter branch­es since the Oc­to­ber snap­shot (tagged snapshot-2013-10) see logs in Cor­rade, Mag­num, Mag­num Plug­ins and Mag­num In­te­gra­tion, re­spec­tive­ly.

For com­pat­i­bil­i­ty branch there is tag snapshot-2014-01-compatibility in Cor­rade, Mag­num and Mag­num Plug­ins repos­i­to­ries.

Google Groups dis­cus­sion

You can now ask for help, share your work or par­ticip­i­ate in de­vel­op­ment at the new Google Groups fo­rum. The group is open to ev­ery­one, you just need Google ac­count to post. In my opin­ion this is bet­ter than re­quir­ing ev­ery­one to cre­ate new ac­count on some self-host­ed fo­rum.

New text ren­der­ing ex­am­ple

I added text ren­der­ing ex­am­ple to show­case new fea­tures such as text align­ment and mul­ti-line text, in ad­di­tion to al­ready ex­ist­ing dis­tance-field ren­der­ing ca­pa­bil­i­ties. See show­case page for live ap­pli­ca­tion run­ning on both Em­scripten and Na­tive Client. I al­so added live Tex­tured Tri­an­gle ex­am­ple.

Textured Triangle Example
Text Example

Us­ing ab­so­lute in­cludes by de­fault

All projects were switched to use ab­so­lute in­cludes by de­fault, i.e. head­ers are in­clud­ed this way:

#include <Magnum/Math/Vector3.h>

rather than this way:

#include <Math/Vector3.h>

This solves many prob­lems with file­name col­li­sions (name­ly with Vis­ual Stu­dio com­pil­er, Doxy­gen and pos­si­bly else­where), see mosra/mag­num#36 for more in­for­ma­tion. As this is a very dras­tic change, you may need to recre­ate your build di­rec­to­ries and up­date at least FindCorrade.cmake and FindMagnum.cmake CMake mod­ules with new ones from modules/ sub­di­rec­to­ry in Cor­rade and Mag­num repos­i­to­ries (and pos­si­bly al­so oth­er ones).

If you are build­ing with dep­re­cat­ed fea­tures en­abled (BUILD_DEPRECATED CMake pa­ram­e­ter in both Cor­rade and Mag­num), you can still use the old non-ab­so­lute in­cludes, but you are en­cour­aged to switch to ab­so­lute ones.

Vis­ual Stu­dio 2013 sup­port

This re­lease is the first one with ex­per­i­men­tal Vis­ual Stu­dio 2013 sup­port. Be­cause the com­pil­er still lacks some re­quired fea­tures (constexpr and noexcept key­words) and has some se­ri­ous bugs in C++11 im­ple­men­ta­tion, the sup­port is pro­vid­ed on­ly through compatibility branch. The port in­volves some ug­ly hacks and work­arounds which can’t be put in master, hope­ful­ly the next MSVC re­lease will make my life eas­i­er. Snap­shot of compatibility branch with MSVC 2013 sup­port is avail­able un­der snapshot-2014-01-compatibility tag in Cor­rade and Mag­num GitHub repos­i­to­ries. The com­pat­i­bil­i­ty branch doesn’t con­tain any­thing new ex­cept work­arounds for said com­pil­ers.

Cor­rade

Dependency changes

No de­pen­den­cy changes in this re­lease.

New features

Changes

  • Test­Suite tests now dis­play ?: <unknown>() in test out­put for test cas­es with­out any checks to make them more dis­cov­er­able
  • Skipped test cas­es in Test­Suite tests are dis­played with­out use­less file/line in­for­ma­tion (un­like failed test cas­es, where the in­for­ma­tion is need­ed)
  • All dep­re­cat­ed func­tions and types are now emit­ting com­pil­er warn­ings to en­cour­age up­dat­ing the code
  • Var­i­ous doc­u­men­ta­tion and ex­am­ple up­dates and im­prove­ments

Bug fixes

  • Test­Suite::Com­pare::*File* is com­par­ing the files in bi­na­ry mode to avoid plat­form-de­pen­dent EOL is­sues.
  • Util­i­ty::Re­source now prop­er­ly han­dles emp­ty files when com­pil­ing re­sources.
  • Util­i­ty::Di­rec­to­ry is now work­ing prop­er­ly un­der Win­dows.
  • Fixed com­pi­la­tion is­sues with Clang and libc++
  • Fixed var­i­ous com­pi­la­tion is­sues un­der MSVC (and worked around a much larg­er amount of com­pil­er bugs)

Deprecated APIs

Removed APIs

  • Re­moved Utility::log2() and Utility::pow2() util­i­ty func­tions, as they weren’t used any­where any­more (and the lat­ter one was a bad joke)
  • Re­moved use­less meta­da­ta from Plug­in­Man­ag­er::Plug­in­Meta­da­ta class (au­thor name, ver­sion, de­scrip­tion), as they don’t fit cur­rent use case any­more (they were used back in 2007 when Cor­rade was part of Kom­pas). These meta­da­ta can be eas­i­ly added back as cus­tom con­fig­u­ra­tion val­ues.
  • Re­moved now use­less Utility::Translator class, it was used on­ly for plug­in meta­da­ta and was prime ex­am­ple of bad de­sign (ex­pos­ing un­guard­ed naked point­ers)

Internal changes

  • Us­ing Jenk­ins Con­tin­u­ous In­te­gra­tion to main­tain com­pi­l­able and bug-free state of the project more eas­i­ly. Cur­rent­ly GCC 4.8, 4.7, 4.6, 4.5, 4.4, Clang 3.3, Clang 3.3 with libc++, Em­scripten, x86-32/x86-64 Na­tive Client and MinG­W32 com­pil­ers are test­ed with both shared and stat­ic li­braries. Sep­a­rate­ly test­ing builds with dep­re­cat­ed fea­tures en­abled and dis­abled.
  • All files from src/ di­rec­to­ry were moved to src/Corrade, examples/ di­rec­to­ry was moved to src/examples (re­quired to make in­ter-project in­cludes ab­so­lute, as men­tioned above)

Mag­num

Dependency changes

No de­pen­den­cy changes in this re­lease.

New features

Changes

  • The magnum-distancefield util­i­ty is now named mag­num-dis­tance­field­con­vert­er for con­sis­ten­cy with oth­er com­mand-line util­i­ties
  • Im­ageRef­er­ence class now stores con­st da­ta point­er in­stead of mu­ta­ble one, mod­i­fy­ing the da­ta through the class in­ter­face isn’t valid use case any­way
  • Added de­fault tem­plate pa­ram­e­ter to Buf­fer::da­ta() and made *Im­age::da­ta() tem­plat­ed to have them con­sis­tent. Note that this is source-com­pat­i­ble change.
  • Query::result<bool>() re­turns true if val­ue is nonze­ro (was re­turn­ing true on­ly for val­ue of 1 pre­vi­ous­ly)
  • All func­tions in Mesh­Tools names­pace are now re­turn­ing ei­ther Con­tain­ers::Ar­ray or std::unique_ptr in­stead of naked point­ers to avoid ac­ci­den­tal out-of-bounds ac­cess and mem­o­ry leaks
  • All func­tions in Text names­pace are now re­turn­ing std::unique_ptr in­stead of naked point­ers to avoid ac­ci­den­tal mem­o­ry leaks
  • Im­ple­men­ta­tion of Plat­form::*Ap­pli­ca­tion::view­portEvent() is not re­quired any­more, be­cause in many cas­es the ap­pli­ca­tion doesn’t need to re­act to win­dow re­size events at all
  • Tex­tured Shaders::Flat now mul­ti­plies tex­ture with the spec­i­fied col­or in­stead of ig­nor­ing it. See al­so mosra/mag­num#34
  • All dep­re­cat­ed func­tions and types are now emit­ting com­pil­er warn­ings to en­cour­age up­dat­ing the code
  • Var­i­ous doc­u­men­ta­tion and ex­am­ple up­dates and im­prove­ments

Bug fixes

  • Fixed Cube­Map­Tex­ture­Ar­ray::im­age() func­tion (more pre­cise­ly it wasn’t work­ing at all). See al­so mosra/mag­num#31.
  • Fixed wrong as­ser­tion in Tex­ture::setWrap­ping() for rec­tan­gle tex­tures
  • Fixed wrong as­ser­tion in AbstractImage::pixelSize() when com­put­ing size of sep­a­rate depth and sten­cil for­mats
  • Mesh::ad­dVer­texBuffer() now prop­er­ly com­putes off­sets for ma­trix at­tributes
  • Tak­ing in­dex buf­fer off­set in­to ac­count in MeshView class
  • Fixed var­i­ous is­sues with tex­tured Shaders::Flat shad­er (ac­tu­al­ly the tex­tured ver­sion was not work­ing at all)
  • Var­i­ous OS X-re­lat­ed fix­es in Shaders li­brary. See al­so mosra/mag­num#27.
  • Fixed build­ing is­sues when both SDL1 and SDL2 is in­stalled on OS X. See al­so mosra/mag­num#25.
  • Fixed build­ing is­sues with CMake-gen­er­at­ed XCode project on OS X. See al­so mosra/mag­num#37.
  • Prop­er and fail­safe OpenGL 3 con­text cre­ation on OS X (3.0 is im­ple­ment­ed on­ly as core con­text, thus re­quest­ing 2.1 won’t ex­pose new­er fea­tures). See al­so mosra/mag­num#26 and mosra/mag­num#35.
  • Fixed com­pi­la­tion is­sues with Clang and libc++
  • Fixed var­i­ous com­pi­la­tion is­sues un­der MSVC (and worked around an in­sane amount of com­pil­er bugs)

Deprecated APIs

Removed APIs

  • Re­moved SceneGraph::*Transformation::move() from 2D trans­for­ma­tion class­es. It was orig­i­nal­ly meant for mod­i­fy­ing draw or­der, but as the draw or­der is man­aged by Scene­Graph::Draw­able­Group class and not by par­ent ob­ject, this func­tion is es­sen­tial­ly use­less.

Internal changes

  • Added thor­ough tests for all core OpenGL func­tion­al­i­ty to make refac­tor­ing eas­i­er
  • Var­i­ous in­ter­nal op­ti­miza­tions and cleanup to make main­te­nance eas­i­er
  • Us­ing Jenk­ins Con­tin­u­ous In­te­gra­tion to main­tain com­pi­l­able and bug-free state of the project more eas­i­ly. Cur­rent­ly GCC 4.8, 4.7, 4.6, 4.5, 4.4, Clang 3.3, Clang 3.3 with libc++, Em­scripten, x86-32/x86-64 Na­tive Client and MinG­W32 com­pil­ers are test­ed with both shared and stat­ic li­braries. Sep­a­rate­ly test­ing builds with dep­re­cat­ed fea­tures en­abled and dis­abled. Al­so ex­plic­it­ly test­ing desk­top OpenGL, OpenGL ES 2.0, desk­top OpenGL ES 2.0 em­u­la­tion, OpenGL ES 3.0 and desk­top OpenGL ES 3.0 em­u­la­tion.
  • All files from src/ di­rec­to­ry were moved to src/Magnum, external/ di­rec­to­ry was moved to src/MagnumExternal (re­quired to make in­ter-project in­cludes ab­so­lute, as men­tioned above)

Mag­num Boot­strap

  • Added new base-sdl2 boot­strap ap­pli­ca­tion so you can start us­ing SDL2 eas­i­er
  • Adapt­ed all boot­strap ap­pli­ca­tions to Mag­num im­prove­ments

Mag­num Plug­ins

Dependency changes

No de­pen­den­cy changes in this re­lease.

New features

  • All class­es in doc­u­men­ta­tion are now shown with cor­re­spond­ing #include path

Changes

Internal changes

  • Us­ing Jenk­ins Con­tin­u­ous In­te­gra­tion to main­tain com­pi­l­able and bug-free state of the project more eas­i­ly. Cur­rent­ly GCC 4.8, 4.7, 4.6, 4.5, 4.4, Clang 3.3, Clang 3.3 with libc++, Em­scripten, x86-32/x86-64 Na­tive Client and MinG­W32 com­pil­ers are test­ed with both shared and stat­ic li­braries. Sep­a­rate­ly test­ing builds with dep­re­cat­ed fea­tures en­abled and dis­abled. Al­so ex­plic­it­ly test­ing desk­top OpenGL, OpenGL ES 2.0, desk­top OpenGL ES 2.0 em­u­la­tion, OpenGL ES 3.0 and desk­top OpenGL ES 3.0 em­u­la­tion.
  • All files from src/ di­rec­to­ry were moved to src/MagnumPlugins (re­quired to make in­ter-project in­cludes ab­so­lute, as men­tioned above)

Mag­num In­te­gra­tion

Dependency changes

No de­pen­den­cy changes in this re­lease.

New features

  • Ini­tial doc­u­men­ta­tion
  • All class­es in doc­u­men­ta­tion are now shown with cor­re­spond­ing #include path

Deprecated APIs

No API was dep­re­cat­ed in this re­lease.

Removed APIs

No dep­re­cat­ed API was re­moved in this re­lease.

Internal changes

  • All files from src/ di­rec­to­ry were moved to src/Magnum (re­quired to make in­ter-project in­cludes ab­so­lute, as men­tioned above)