Merge remote-tracking branch 'remotes/origin/master' into dev

# Conflicts:
#	examples/HelloWorld/src/entry_point.cpp

examples/HelloWorld/src/entry_point.cpp

@@ -1,8 +1,8 @@
 /**
-Attention!
-This file has Oxygine initialization stuff.
-If you just started you don't need to understand it exactly you could check it later.
-You could start from example.cpp and example.h it has main functions being called from there
+	Attention!
+	This file initializes the Oxygine engine.
+	If you just started here and don't understand the code completely, feel free to come back later.
+	You can start from example.cpp and example.h, which main functions are called from here.
 */
 #include "core/oxygine.h"
 #include "Stage.h"
@@ -14,46 +14,48 @@ You could start from example.cpp and example.h it has main functions being calle
 using namespace oxygine;
 
 
-//called each frame
+// This function is called each frame
 int mainloop()
 {
+	// It gets passed to our example game implementation
     example_update();
-    //update our stage
-    //update all actors. Actor::update would be called also for all children
+
+    // Update our stage
+    // Update all actors. Actor::update will also be called for all its children
     getStage()->update();
 
     if (core::beginRendering())
     {
         Color clearColor(32, 32, 32, 255);
         Rect viewport(Point(0, 0), core::getDisplaySize());
-        //render all actors. Actor::render would be called also for all children
+        // Render all actors inside the stage. Actor::render will also be called for all its children
         getStage()->render(clearColor, viewport);
 
         core::swapDisplayBuffers();
     }
 
-    //update internal components
-    //all input events would be passed to Stage::instance.handleEvent
-    //if done is true then User requests quit from app.
+	// Update engine-internal components
+	// If input events are available, they are passed to Stage::instance.handleEvent
+	// If the function returns true, it means that the user requested the application to terminate
     bool done = core::update();
 
     return done ? 1 : 0;
 }
 
-//it is application entry point
+// Application entry point
 void run()
 {
     ObjectBase::__startTracingLeaks();
 
-    //initialize Oxygine's internal stuff
+    // Initialize Oxygine's internal stuff
     core::init_desc desc;
     desc.title = "Oxygine Application";
 
 #if OXYGINE_SDL || OXYGINE_EMSCRIPTEN
-    //we could setup initial window size on SDL builds
+	// The initial window size can be set up here on SDL builds
     desc.w = 960;
     desc.h = 640;
-    //marmalade settings could be changed from emulator's menu
+    // Marmalade settings can be modified from the emulator's menu
 #endif
 
 
@@ -61,7 +63,7 @@ void run()
     core::init(&desc);
 
 
-    //create Stage. Stage is a root node
+    // Create the stage. Stage is a root node for all updateable and drawable objects
     Stage::instance = new Stage(true);
     Point size = core::getDisplaySize();
     getStage()->setSize(size);
@@ -69,51 +71,51 @@ void run()
     //DebugActor is a helper actor node. It shows FPS, memory usage and other useful stuff, also it initializes some default resourcess
     DebugActor::show();
 
-    //initialize this example stuff. see example.cpp
+	// Initializes our example game. See example.cpp
     example_init();
 
 #ifdef EMSCRIPTEN
     /*
-    if you build for Emscripten mainloop would be called automatically outside.
-    see emscripten_set_main_loop below
+    If you build for Emscripten, mainloop is called automatically and shouldn't be called here.
+    See emscripten_set_main_loop in the EMSCRIPTEN section below
     */
     return;
 #endif
 
 
-    //here is main game loop
+    // This is the main game loop.
     while (1)
     {
         int done = mainloop();
         if (done)
             break;
     }
-    //user wants to leave application...
+    // If we get here, the user has requested the Application to terminate.
 
-    //lets dump all created objects into log
-    //all created and not freed resources would be displayed
+    // We dump and log all our created objects that have not been freed yet
     ObjectBase::dumpCreatedObjects();
 
-    //lets cleanup everything right now and call ObjectBase::dumpObjects() again
-    //we need to free all allocated resources and delete all created actors
-    //all actors/sprites are smart pointer objects and actually you don't need it remove them by hands
-    //but now we want delete it by hands
+	/*
+	Let's clean up everything right now and call ObjectBase::dumpObjects() again.
+	We need to free all allocated resources and delete all created actors.
+	All actors/sprites are smart-pointer objects and don't need to be removed by hand.
+	But now we want to delete it by hand.
+	*/
 
-    //check example.cpp
+    // See example.cpp for the shutdown function implementation
     example_destroy();
 
-
     //renderer.cleanup();
 
-    /**releases all internal components and Stage*/
+    // Releases all internal components and the stage
     core::release();
 
-    //dump list should be empty now
-    //we deleted everything and could be sure that there aren't any memory leaks
+    // The dump list should be empty by now,
+    // we want to make sure that there aren't any memory leaks, so we call it again.
     ObjectBase::dumpCreatedObjects();
 
     ObjectBase::__stopTracingLeaks();
-    //end
+    // end
 }
 
 #ifdef __S3E__

oxygine/src/core/STDFileSystem.cpp

@@ -96,8 +96,10 @@ namespace oxygine
         void oxFileClose(oxHandle* file)
         {
             if (file)
+            {
                 _openedFiles--;
-            oxFileClose_(file);
+                oxFileClose_(file);
+            }
         }
 
 

readme.md

@@ -1,14 +1,14 @@
 # BUILD AND RUN   
-See **oxygine-framework/readme/** folder. It has insructions how to build and run oxygine on different platforms.
+See **oxygine-framework/readme/** folder. It has instructions on how to build and run oxygine on different platforms.
 
 # Wiki available at
 https://github.com/oxygine/oxygine-framework/wiki
 
 
-# Oxygine is C++ engine for 2D mobile games. 
-One more shell around OpenGL/D3D API you would say? No, this is a set of classes and tools to create a game according to your requirements.
+# Oxygine is a C++ engine for 2D mobile games. 
+Yet another shell around OpenGL/D3D API you would say? No, this is a set of classes and tools to create a game according to your requirements.
 
-In the basis of the engine there is a scene graph, that is similar to Flash one. To be short, You can call this as Flash for C++, but more comfortable and way faster. Initially it was developed for mobile platforms (iOS, Android), but can be also used for PC games.
+At the basis of the engine there is a scene graph, that is similar to Flash. In short, You can call this as Flash for C++, but more comfortable and way faster. Initially it was developed for mobile platforms (iOS, Android), but can also be used for PC games.
 
 Source code is available under MIT license (use for free anywhere).
 
@@ -52,32 +52,32 @@ sprite->addEventListener(TouchEvent::CLICK, [sprite](Event*){
 - For rendering OpenGL(ES) 2.0 is used. Custom shaders supported.
 - Compressed textures supported.
 - Component based system, simple and predictable OOP API. Possibility to inherit from classes and overload their behavior.
-- No global mega managers of everything, that dictates requirements to the way you write your code.
+- No global mega managers of everything, that dictate the requirements and the way you write your code.
 - Effective and flexible work with resources, very close to your game.
 - Components of the engine have weak links between each other. Can be used together, separately or not at all.
 - Fast creation and deletion of objects using memory pools for all engine objects.
-- SceneGraph is somewhat similar to Flash ([diagrams with inheritance models](https://dl.dropbox.com/u/12679384/oxygine/actor_inheritance.png)). It is built on smart pointers (analogue boost:intrusive_ptr). No need to hassle with memory control, memory leaks. 
-- Debug Tools ([screenshot](https://dl.dropboxusercontent.com/u/12679384/oxygine/debug_tools.gif)). Tree Inspector is “Visual profiler” for Scene Graph. Right in the game you can view the graph and different branches to analyze and errors search. “Textures Inspector” shows you currently loaded textures into memory ([screenshot](https://dl.dropbox.com/u/12679384/oxygine/textures_inspector.png))
+- SceneGraph is somewhat similar to Flash ([diagrams with inheritance models](http://i.imgur.com/DO5WFUA.png)). It is built on smart pointers (analogue boost:intrusive_ptr). No need to hassle with memory control, memory leaks. 
+- Debug Tools ([screenshot](http://i.imgur.com/77aGg82.gif)). Tree Inspector is “Visual profiler” for Scene Graph. Right in the game you can view the graph and different branches to analyze and errors search. “Textures Inspector” shows you currently loaded textures into memory ([screenshot](http://i.imgur.com/Znynji4.png))
 - Render to texture.
 - Resources description is stored in xml file. It has multiple different parameters: you can add your own resources types, format can be set, in which you will store the texture(atlas) in memory, number of columns and rows for animation, etc. Any resource can have user-data attributes.
-- Tweens for frame by frame animation, color, position, rotation, etc. Your own can be easily created.
-- Set of basic UI components commonly used in games: Button, Sprite, ProgressBar and others ([image](https://dl.dropboxusercontent.com/u/12679384/oxygine/actor_inheritance.png))
+- Tweens for frame-by-frame animation, color, position, rotation, etc. Easily create your own.
+- A set of basic UI components commonly used in games: Button, Sprite, ProgressBar and others ([image](http://i.imgur.com/IUxKi7O.png))
 Command-line tool on Python to process your resources: Build you resources from XML files into atlases, determining the optimal size of atlases. Resize assets from high-res to necessary for your game. Does additional work to optimize work with resources in the game. Compress automatically to ETC1 or PVRTC textures format.
 - Well-designed handling of events from mouse and multi-touch (for example you can press two buttons with two fingers at the same time without collisions) based on AS3 Flash model.
 - It is possible to write code and dialogs in blocking style (concurency programming/coroutines).
-- Accurate rendering of text with line wraps, vertical and horizontal alignment support, localization, utf-8. Base HTML tags support ([screenshot](https://dl.dropboxusercontent.com/u/12679384/oxygine/text_align.gif)).
+- Accurate rendering of text with line-wraps, vertical and horizontal alignment support, localization, utf-8. Base HTML tags support ([screenshot](http://i.imgur.com/x66UTR3.gif)).
 - If you want to add multiple sets of assets for different game resolutions it can be done on the engine level by writing just a few lines of code. You won’t need to adjust coordinates manually for different resolution. It is enough just to keep initial art in high-res.
-- Masking ([screenshot](https://dl.dropboxusercontent.com/u/12679384/oxygine/masking.gif), [screenshot](https://dl.dropboxusercontent.com/u/12679384/oxygine/mask.png))
-- Atlas assembling on the fly during the loading, if you didn't make it before.
+- Masking ([screenshot](http://i.imgur.com/dxSUVGX.gif), [screenshot](http://i.imgur.com/wAhd6BG.png))
+- Atlas assembling on the fly during the loading, if you didn't provide it yourself.
 - Multi-threaded resources loading.
-- It is possible to partially unload from memory “heavy” resources, like atlases. The resouce handle to work with atlas will be still valid (as well as his size) and will even have texture point, but the texture itself will be empty. This is very important when you have strict memory limitations: for example if you created all UI with all resources loaded, but there is no need to display them.
+- It is possible to partially unload “heavy” resources like atlases from memory. The resouce handle to work with atlas will be still valid (as well as its size) and will even have texture points, but the texture itself will be empty. This is very important when you have strict memory limitations: for example if you created the whole UI with all resources loaded, but there is no need to display them all at once.
 - Fast automatic batching.
 - Bitmap fonts based on [BMFont](http://www.angelcode.com/products/bmfont/) and FreeType. Possibility to add your own font type.
 
-You could build it on top of the Marmalade, SDL2 or adapt it for your platform. Oxygine could be build with Emscripten for internet browser as well.
+You could build it on top of Marmalade, SDL2 or adapt it for your platform. Oxygine can be built with Emscripten for internet browsers as well.
 
-And this is not all. There are a lot of features, but it is easy to use them, framework is not a monster and very intuitively clear. Viewing of couple examples would be enough to understand how it works.
+And this is not everything. There are a lot of easy-to-use features, this framework is not a monster and is clear and intuitive. Viewing a couple of examples is enough to understand how it works.
 
 
 ##Contacts
-You could find more information on [oxygine.org](http://oxygine.org)
+You can find more information at [oxygine.org](http://oxygine.org)

readme/VisualStudio.txt

@@ -1,7 +1,7 @@
 1. Start from readme.txt
 
-Ff you are using Oxygine All-In-One version with SDL included you could skip #2
-just go to any example and open it
+If you are using the Oxygine All-In-One version with SDL included, you can skip #2
+and just go to any example and open it right away
 
 2. There are prebuilt example solutions for VS2010+
 =================================================================================================
@@ -13,25 +13,23 @@ just go to any example and open it
     //#define SDL_AUDIO_DRIVER_XAUDIO2    1
   - Go to folder SDL\VisualC\ 
   - Open SDL.sln and build it in Release configration
-  - Goto golder SDL\VisualC\Win32\Release\
+  - Go to folder SDL\VisualC\Win32\Release\
   - and copy SDL2.lib, SDL2main.lib and SDL2.dll to oxygine-framework/libs
 
-- Go to oxygine-framework\examples and choose any example. For example "Demo"
-- Open solution located in oxygine-framework\examples\Demo\proj.win32\
-- Try to build Demo
-- Copy all dlls from  oxygine-framework\oxygine\third_party\win32\dlls\
-   and SDL2.dll from oxygine-framework/libs 
-   to  oxygine-framework\examples\Demo\data\   
-- Working directory of Demo project should point to "../data" folder (right mouse click on Demo -> project->properties->ConfigurationProperties->Debugging->WorkingDirectory)
+- Go to oxygine-framework\examples and choose any example, for example "Demo"
+- Open the solution located in oxygine-framework\examples\Demo\proj.win32\
+- Try to build the Demo
+- Copy all dlls from oxygine-framework\oxygine\third_party\win32\dlls\
+   and SDL2.dll from oxygine-framework/libs
+   to: oxygine-framework\examples\Demo\data\
+- The working directory of the Demo project should point to the "../data" folder (right mouse-click on the "Demo" Project -> Properties -> "Configuration Properties" -> Debugging -> "Working Directory")
 - ready! run!
 =================================================================================================
 
-3. You could generate your own Solution anywhere
+3. You can generate your own Solution anywhere you want:
 - You need Python 2.7 installed
 - you need to run this script
   oxygine-framework\tools\gen_template.py
 
 example:
 	python gen_template.py MyProject -t win32 -d path/to/MyProject/
-	
-

readme/readme.txt

@@ -1,15 +1,15 @@
 If you are using:
 	- SDL2:
-		1. Download latest the SDL2 source snapshot from http://libsdl.org/hg.php
-		2. Your folder structure should be orginized this way:
+		1. Download latest SDL2 source snapshot from http://libsdl.org/hg.php
+		2. Your folder structure should be orginized like this:
 			any/path/
 					/oxygine-framework
 					/SDL
 
 		3. Check other instructions for your platform:
-			- VisualStudio.txt has insructions how to build Oxygine with Visual Studio on Windows
-			- Android.txt has insructions how to build Oxygine for Android
-			- CMake.txt has instructions how to build Oxygine with CMake on Windows and Linux
-			- iOS.txt and MacOSX.txt instuctions how to build Oxygine with XCode
+			- VisualStudio.txt has instructions on how to build Oxygine with Visual Studio on Windows
+			- Android.txt has instructions on how to build Oxygine for Android
+			- CMake.txt has instructions on how to build Oxygine with CMake on Windows and Linux
+			- iOS.txt and MacOSX.txt have instructions on how to build Oxygine with XCode
 
-	- Marmalade. Then read Marmalade.txt
+	- Marmalade: Read Marmalade.txt