Porting notes

From 1.4 to 1.5:

• Urho preprocessor macros are now prefixed URHO3D_ , for example URHO3D_LOGINFO, URHO3D_HANDLER, URHO3D_DEFINE_APPLICATION_MAIN.
• Build system - for projects using GCC/Clang compiler toolchain, set the URHO3D_DEPLOYMENT_TARGET build option according to the target audience of the downstream projects. The default value for this build option is 'native' which is great for Urho3D newbie but may potentially cause issue when this build option is not observed and set accordingly for production. The same is true for CMAKE_OSX_DEPLOYMENT_TARGET and IPHONEOS_DEPLOYMENT_TARGET build options when targeting macOS and iOS platforms, however, the latter two build options are not new.

From 1.5 to 1.6:

• The keycode constant KEY_ESC was renamed to KEY_ESCAPE to match SDL's convention.
• Alphabetic keycode constants are now lowercase to match SDL's convention. It's preferable to always use these constants instead of character literals. For compatibility, passing uppercase letters to e.g. Input::GetKeyDown() still works, but comparing to uppercase literals in key event handling will cause a mismatch and non-functioning controls.
• Bitmask based vertex declarations are emulated by converting to corresponding VertexElement declarations. This should not cause issues, but it's recommended to migrate to VertexElement based declarations for better flexibility and control, and to go through any application code that uses the VertexBuffer class to verify correctness.
• As part of the freeform vertex declaration change, GLSL vertex attributes' semantic indices are now zero-based. The first texcoord would be called iTexCoord or iTexCoord0, and the second iTexCoord1. This matches HLSL semantics that are also zero-based. Instance transform is passed in texcoord semantic indices 4-6 on both GLSL & HLSL.
• cCameraRot matrix uniform has been removed. Camera rotation can instead be extracted from the cViewInv uniform.
• Deferred lighting calculations are now performed in true world space, instead of camera-centered world space.
• SoundSource autoremove functionality is deprecated and will be removed in the future. The SoundFinished event can be used instead to react to playback finishing and to perform the necessary action, for example to remove the sound component or its owner node.
• String add operator with char parameter has been removed due to danger of truncating e.g. an int. Replace with adding a string literal (if applicable) or using add-assign or Append() function.
• Build system - Windows users need to upgrade CMake version to 3.2.3 or higher. CMake version 3.2.3 will be the minimum version required for building Urho3D library on any host systems in the future releases. Mac users need to upgrade CMake version to 3.4.1 or higher when using URHO3D_LUAJIT build option.
• Build system - the inclusion of Urho3D-CMake-common.cmake module into downstream project's CMakeLists.txt would implicitly instruct CMake to find all the required software packages, including Urho3D library. There is no need now for downstream's CMakeLists.txt to call "find_package (Urho3D)" explicitly, to avoid the Urho3D library from being searched twice. The enhanced FindUrho3D.cmake module now auto-discovers the build options used when building Urho3D library and reapply them to downstream projects. There is no need for users to remember and to supply the same set of build options when performing the initial configuration/generation of the downstream project's build tree.
• Build system - the Urho3DAll.h header file is now auto-generated for downstream project that needs it. It is not a good practice though to use this "convenience header" as it would slow down the build process unnecessarily.

From 1.6 to 1.7:

• SoundSource autoremove boolean was replaced with AutoRemoveMode enum, which allows removing either the component or owner node. Also used by ParticleEmitter.
• Getting camera projection matrix has changed. Use GetProjection() to get the API-independent matrix, and GetGPUProjection() to get the matrix converted to be usable as a shader parameter. On D3D these are the same.
• Alpha masking hint has been removed from Technique & Pass, due to materials also now being able to define additional shader compilation defines. You can use Material::SetRenderOrder() instead to ensure that partially opaque geometry will be drawn after fully opaque for GPU depth buffer optimization. Due to this change you must also manually define that a material should not take part in occlusion rendering, see Material::SetOcclusion().
• Techniques that existed just for shader defines like ALPHAMASK and PACKEDNORMAL have been removed. Replace by using techniques without those defines (e.g. DiffNormal instead of DiffNormalPacked), and adding the necessary defines to your materials instead.
• The Light class has gained a max extrusion distance parameter for directional light shadows. In case you use a large far clip distance, you can experience different shadow depth resolution and effect of bias parameters, as the far clip distance no longer alone determines the extrusion. Adjust with Light::SetShadowMaxExtrusion() as necessary.
• Direct3D binary shaders are now cached by default to the user preferences directory "urho3d/shadercache" to avoid writing into the application installation directory, to which the user may not have rights. If you ship a prewarmed (read-only) cache with your application you can set the directory yourself from the engine startup parameter "ShaderCacheDir" or call Graphics::SetShaderCacheDir() on initialization. Use the directory "Shaders/HLSL/Cache" to get the old behavior.
• Signatures of UIElement virtual functions OnResize() and OnPositionSet() have changed.
• The Font class and related classes take font size as a float instead of int to allow fractional point sizes. Glyphs themselves may also have fractional positions, so floats are now used internally in text rendering.
• UIElement::LoadChildXML() now returns the created element on success, instead of a boolean.
• Rendertargets have gained the ability to have automatically regenerated mipmaps. Screen buffers received from the Renderer subsystem have mipmaps off, but for manually created rendertargets the default is mipmaps on, like for ordinary textures. Use SetNumLevels(1) to disable.
• The shader function GetWorldTangent() now returns a 4-component vector.
• AnimatedModel allows unclamped morph weights, also negative.
• StaticModel::SetModel() will no longer warn and redirect to AnimatedModel::SetModel() if the wrong function is called from C++ code. The AngelScript API will instead redirect properly without producing a warning.
• Graphics::SetMode(), Graphics::GetDesktopResolution() and Graphics::GetResolutions() have gained an extra parameter to specify the monitor to use. Use Graphics::GetMonitorCount() to get the number of attached monitors. Monitor number 0 means the default primary monitor.
• P_CONTACT parameter was removed from 2D physics collision events. Use P_CONTACTS buffer instead.
• GetPlatform() function returns "macOS" instead of "Mac OS X".
• Build system - the "Urho3D-CMake-common.cmake" file is now renamed to "UrhoCommon.cmake".
• Build system - downstream project is now responsible to add the HTML shell-file by calling the add_html_shell() macro or by passing "HTML_SHELL" option when calling the define_resource_dirs() in order to generate the HTML output when targeting Web platform, i.e. the build system defaults to JS output now, except when URHO3D_TESTING build option is set. When URHO3D_TESTING is set then it is assumed the output should be test runnable by using emrun, therefore the build system will automatically add the default HTML shell-file if none has been added yet.
• Build system - when targeting macOS platform, the build tree will be configured to only target x86_64 arch by default as we are phasing out 32-bit mode. Use the URHO3D_UNIVERSAL build option, if you still want the universal binary build.