Update readme

Samples/basic/benchmark/src/main.cpp

@@ -94,6 +94,7 @@ public:
 		  EventIDs: 139.0  [d2c3956]
 		  More on events and EventIDs: 146.0  [fd44d9c]
 		  New decorator and font-effect syntax and misc (on a considerably lower clocked CPU): 156 [6619ab4]
+		  Removal of manual reference counting: 170 [cb347e1]
 		  
 		*/
 

readme.md

@@ -150,6 +150,63 @@ When creating a custom font-effect, you can provide a shorthand property named `
 There is currently no equivalent of the `@decorator` at-rule for font-effects. If there is a desire for such a feature, please provide some feedback.
 
 
+
+### Removal of manual reference counting
+
+All manual reference counting has been removed in favor of smart pointers. There is no longer a need to manually decrement the reference count, such as `element->RemoveReference()` as before. This change also establishes a clear ownership of objects. For the user-facing API, this means raw pointers are non-owning, while unique and shared pointers declare ownership. Internally, there may still be uniquely owning raw pointers, as this is a work-in-progress.
+
+#### Core API
+
+The Core API takes raw pointers as before such as for its interfaces. With the new semantics, this means the library retains a non-owning reference. Thus, all construction and destruction of such objects is the responsibility of the user. Typically, the objects must stay alive until after `Core::Shutdown` is called. Each relevant function is commented with its lifetime requirements.
+
+As an example, the system interface can be constructed into a unique pointer.
+```C++
+auto system_interface = std::make_unique<MySystemInterface>();
+Rml::Core::SetSystemInterface(system_interface.get());
+Rml::Core::Initialise();
+...
+Rml::Core::Shutdown();
+system_interface.reset();
+```
+Or simply from a stack object.
+```C++
+MySystemInterface system_interface;
+Rml::Core::SetSystemInterface(&system_interface);
+Rml::Core::Initialise();
+...
+Rml::Core::Shutdown();
+```
+
+#### Element API
+
+When constructing new elements, there is again no longer a need to decrement the reference count as before. Instead, the element is returned with a unique ownership
+```C++
+ElementPtr ElementDocument::CreateElement(const String& name);
+```
+where `ElementPtr` is a unique pointer and an alias as follows.
+```C++
+using ElementPtr = std::unique_ptr<Element, Releaser<Element>>;
+```
+Note that, the custom deleter `Releaser` is there to ensure the element is released from the `ElementInstancer` in which it was created.
+
+After having called `ElementDocument::CreateElement`, the element can be moved into the list of children of another element.
+```C++
+ElementPtr new_child = document->CreateElement("div");
+element->AppendChild( std::move(new_child) );
+```
+Since we moved `new_child`, we cannot use the pointer anymore. Instead, `Element::AppendChild` returns a non-owning raw pointer to the appended child which can be used. Furthermore, the new element can be constructed in-place, e.g.
+```C++
+Element* new_child = element->AppendChild( document->CreateElement("div") );
+```
+and now `new_child` can safely be used until the element is destroyed.
+
+There are aliases to the smart pointers which are used internally for consistency with the library's naming scheme.
+```C++
+template<typename T> using UniquePtr = std::unique_ptr<T>;
+template<typename T> using SharedPtr = std::shared_ptr<T>;
+```
+
+
 ### Other changes
 
 - `Context::ProcessMouseWheel` now takes a float value for the `wheel_delta` property, thereby enabling continuous/smooth scrolling for input devices with such support. The default scroll length for unity value of `wheel_delta` is now three times the default line-height multiplied by the current dp-ratio.
@@ -167,6 +224,7 @@ Breaking changes since RmlUi v2.0.
 - Removed RenderInterface::GetPixelsPerInch, instead the pixels per inch value has been fixed to 96 PPI, as per CSS specs. To achieve a scalable user interface, instead use the 'dp' unit.
 - Removed 'top' and 'bottom' from z-index property.
 - See changes to the declaration of decorators and font-effects above.
+- Also, see removal of manual reference counting above.
 
 
 #### Events