Merge pull request #138 from schmouk/dev

Dev - cpp14 v.0.1 ready

Author: schmouk

.gitignore

@@ -36,6 +36,15 @@
 *.vcxproj
 *.vcxproj.*
 *.sln
+x84
+Release
+Debug
 
 # External Documentaion
 docs
+
+# This project specifics
+archive
+cpp-bmp-loader
+create_ba_files
+tests

README.md

@@ -1,43 +1,88 @@
 # CppBMPLoader
 An exhaustive BMP Loader, MIT-licensed, implemented for c++14 and c++20
 
+This BMP loader library decodes **Windows** BMP files encoded according to 
+BMP format versions 1 up to 5, as well as the specific *OS/2 1.x* and *OS/2 
+2.x* BMP (*BitMaP*) and BA (*Bitmap multi images Array*) file formats.
+
+It nevertheless currently does not decode JPEG and PNG encoded images that 
+are embedded in BMP files, nor does it decode images embedding Windows 
+color profiles.
 
 ## Genesis of this project
-The genesis of this project is the initial creation of the **OGLFW** library, 
-an object overlay of the **GLFW** library, and the need to associate it with 
-a library for loading images under the **MIT license** or from the public 
-domain, free of rights, to associate them with icons provided in OGLFW. 
-
-## No way to find such a library - Alternative
-Being unable to find such a library under this type of license, a solution 
-was to let users of the original **OGLFW** library load the images themselves 
-using the external library of their choice, even if not under the MIT license.
-
-Another solution was to propose an `Icon` class with a virtual image loading 
-method not implemented in this base class. This second solution allowed users 
-to derive their own classes from this Icon base class and to implement the 
-image loading method corresponding to the format of the images to be loaded 
-(possibly using already existing but less permissively licensed libraries). 
-To this end, and as an example of implementation, a `BMPIcon` derived class 
-has been provided in the **OGLFW** library. Its implementation had to rely on 
-an external library which allows the loading of **BMP** images. Unfortunately, 
-no library met the required licensing criteria or, when unlicensed or under 
-**MIT** license, did not allow decoding of all cases of BMP image encoding.
+The genesis of this project is the initial creation of another library that
+needed to be associated with an external library for loading BMP images under
+the **MIT license** or from the public domain, free of rights, to associate 
+them with icons. 
+
+Unfortunately, no such library has been found under this type of license that 
+would provide for the decoding of **all** the different standardized formats of 
+BMP images.
 
 ## CppBMPLoader is the implemented solution
 The **CppBMPLoader** library therefore fills this gap by offering the only 
 loading of **BMP** images in all the forms that this image format allows and 
 under the permissive MIT license. It will also meet many other needs when one 
-sees the quantity of questions asked on this subject on the Internet and the 
-number of BMPLoader libraries already existing but apparently incomplete that 
+sees the number of questions asked on this topic on the Internet and the 
+number of BMPLoader libraries already existing, but apparently incomplete, that 
 can be found on *GitHub*, programmed in c++ or in other programming languages.
 
 ## c++14 and c++20 versions
-Initially, two versions of the library are offered, one responding to standard 
-c++14 of the programming language and the other responding to standard c++20 
-and offering more advanced programming concepts (e.g. programmed in the form 
-of c++ modules).
-
-## Notice
-Notice: by April and May 2024, this original library **OGLFW** is still under 
-development.
+Initially, two versions of the library are offerred, one responding to standard 
+c++14 and the other responding to standard c++20 (offering more advanced 
+programming concepts, e.g. *ranges* and *views* or STL extensions).
+
+Notice: by November 2024, the c++20 version of the library is not yet released.
+
+## Notice (1/2)
+The c++14 standard version of **CppBMPLoader** does not use any c++14 
+specificities but only c++11 ones. It has been compiled and validated with
+a c++14 compiler but should as well be compilable with a c++11 compiler.
+
+## Notice (2/2)
+All released code has been validated. For this purpose, we used the great
+[**BMP Suite Image List**](https://entropymine.com/jason/bmpsuite/bmpsuite/html/bmpsuite.html)
+provided by Jason Summers - see also 
+[https://entropymine.com/jason/bmpsuite/](https://entropymine.com/jason/bmpsuite/)
+and we augmented it with images we created by our own for the version 1 of Windows 
+BMP format (lacking in Jason's suite) and with OS/2 **BA** files that we either 
+created from scratch or downloaded from the Web, extracted from some original 
+ISO images of OS/2.
+
+
+# Documentation
+The API of **CppBMPLoader** is documented in [documentation.md](./documentation.doc).
+This API is exactly the same for both the c++14 and the c++20 implementations of
+the library.
+
+Shortly speeking, this API offers a templated class BMPImage<> for the loading 
+of BMP images content and classes and functions to extract and load all images 
+from a **BA** file or just the one of them that best fits dimensions, colors 
+and/or resolutions criterias.
+
+Many error cases and warnings are detected by **CppBMPLoader**. Errors are always 
+fatal. Execution stops on any encountered error. Warnings do not stop your 
+application and are accumulated along the processing of BMP and BA files. You 
+get access to the error code and to a list of warning codes as well to the 
+associated messages at will, since they are attached to the faulty BMP images.
+
+
+# Reading the code
+For those of you who are the most motivated for deeply diving into this 
+library code, please notice that no implementation documentation is provided 
+for **CppBMPLoader**.
+
+The design decision made for its first implementation, a.k.a. cpp-14, has been 
+to factorize as much code as possible. This was a tremendous decision when at 
+bugs fixing time: each bug had to be fixed in one and only one place. This was 
+also a very deceptive decision about the final readability of the code. So, you 
+should avoid to have a first look at this code. Prefer to go into the c++20 
+implementation of **CppBMPLoader** instead to have a far easier reading of it. 
+There, we've preferred to duplicate the already debugged code, to provide a 
+clear class for each type of object and for each format version that is 
+internally managed by the library.
+
+Meanwhile, experienced c++ developers should get no trouble in understanding 
+the directories tree structure and the code itself as well, which is 
+commented everywhere it seemed to be useful.  
+See directories **cpp-14** or **cpp-20** and enjoy!