﻿/*
	© 2013-2014 FrankHB.

	This file is part of the YSLib project, and may only be used,
	modified, and distributed under the terms of the YSLib project
	license, LICENSE.TXT.  By continuing to use, modify, or distribute
	this file you indicate that you have read the license and
	understand and accept it fully.
*/

/*!	\file Workflow.Annual2013.txt
\ingroup Documentation
\brief 工作流汇总报告 - 2013 年度。
\version r267
\author FrankHB <frankhb1989@gmail.com>
\since build 433
\par 创建时间:
	2013-07-31 01:27:41 +0800
\par 修改时间:
	2013-12-26 00:50 +0800
\par 文本编码:
	UTF-8
\par 模块名称:
	Documentation::Workflow::Annual2013
*/

// See "Meta.cpp" for meta descriptions.

$import $WORKFLOW;
$LINE-WIDTH-RESTRICT 0;

$WORKFLOW:
// Following lines are only for logging informal project information.
// See Meta.txt for formal project information.
// See ChangeLog.*.txt for accepted contents.

$2013-04:

report.anylatical:
Primative image formats should be supported: bmp, jpg, png.
Use non-GPL for license of FreeImage.

workflow.dev-dep:
For UI:
	(literal semantics, function mapping) -> NPL evaluator,
	UI layout manager -> UI designer,
	(concreate UI sessions, UI session manager) -> UI session shells,
	device abstraction -> platform surfaces,
	(YEGE, graphical layer adaptors) -> YSLib graphical APIs;

note.visual-stack:
Reconstruction of visual stack design should be considerable.
	currently: host screen/desktop layer - hosted window - YSLib screen device with back buffer/platform surface - Desktop;
	future: all layers handled via %IWidget derived class components;

todo.designated:
/ device-reqirement-analysis;
/ image-reqirement-analysis, round 2;

$2013-05:

report.impl:
See $known_issue_b406 @ Meta.txt.

dep.merge:
Microlua(github://microlua/MicroLua-Source) @ DS: considerable, shelved.
uLibrary @ DS: rejected. Quality questionable, not suitible for scope.
	From http://devkitpro.org/viewtopic.php?f=2&t=3192, WinterMute: "Please don't use uLibrary either, it's awful and you won't get support for it here either."

note.req-env:
WG21/N3476 is confirmend to be not needed currently.

$2013-06:

report.impl:
Resolved bug $known_issue_b223.

todo.ceased:
Base class 'noinstance' is not necessary. Use abstract class to stop create an object of a class.

todo.deferred:
$done.finished Updating dependencies of FreeImage.
	// To make binary change small.

note.design:
UI input/output events should be asymmetry, that is, input events are far more variant than output events. The reasons are:
	1. There are more unpredictable choices from user input than program output by the designer.
	2. The output is usually generated by few kinds of devices(video and audio), but the input is often from a lot more devices with different types and behavior.
	3. Though the input from variant devices can be multiplexed, they are almost always demultiplexed by the client, if used. No need to twist them together for both input and output events.

$2013-07:

dep.impl:
FreeType:
	Modules configuration:
	'HINTING_MODULES += autofit' is to be removed for no necessity of hinting and binary size.
	'AUX_MODULES += cache' is to be removed because only the header is used currently.
	Redundant, unused and invalid(dependency not satisfied) 'BASE_EXTENSIONS += ftfstype.c' is to be removed.
	'BASE_EXTENSIONS += ftstroke.c' is to be removed because currently not needed.
	'BASE_EXTENSIONS += ftsynth.c' is to be removed because this is the alpha interface(see the source) , and should be considered deployed in client code.
	Performance:
	Old version of FreeType source files are used for workaround. See $known_issue_b406 @ Meta.txt.

report.impl:
See $known_issue_b406 @ Meta.txt.
	Hotspot history in freetype2 repository: tt_face_get_metrics @ ttmtx.c:f5aa47b, tt_face_get_metrics @ ttgload.c:8744edf, TT_Get_Metrics @ ttgload.c:3ab770b.
There is no necessity for attatched events implemented as routed events like WPF built in GUI state of YSLib, because:
	1. Basically routed events fit view trees well.
	2. No no other trees used as part constructs for further UI modeling which have extra routes.
Though event forwarding with distinct source switched or attatched can be reasonable.
New UI event CursorOver and CursorWheel supported. Though no need for devices without mouse like DS, it is a plus to allow users raise such events.
Some bugs of screen coordinate conversion for MinGW32 fixed.
Wheel event issues:
	Scroll bars and listboxes now support CursorWheel event. More should be investigated.
	Now wheel event is available in the area of independent focus. Extended wheel event can be supported when cursor out of area of current widget(independent focus) like QQ2013 UI, but is depend on users.
Using seperated 'Fetch*' function to get static objects for:
	1. Runtime dependency can be decreased. If font cache is not needed, font directory is also not needed to be specified.
	2. It is good for statically-linked programs without need for initialization of all these objects. Binary image size can be decreased through link-time optimization if the unrelated interface is unused totally.
Some interfaces of 'Helper' are moved to 'YSLib'. Some(like 'FPSCounter') are still immature.
Win32 hosted Window enumeration:
	::EnumWindows and ::EnumChildWindows can not keep iteration state, so use ::GetWindow instead.
	Results of enueration the desktop are often too large for usual application.
G++ 4.8.1 wrongly accepted reopened namespace from non-line to inline. See http://gcc.gnu.org/bugzilla/show_bug.cgi?id=53402 .
For loading image from file system using FreeImage:
	Non-ANSI file name for extension detection(i.e. for ::FreeImage_GetFIFFromFilename) is OK, because the extensions recognized are all ASCII representable.
	Unicode version of functions are invalid for non-Win32 platforms, so just do not use them.
	Do not use ::FreeImage_Load if the encoding of file name used by ::fopen is not specified.
For %::NTSTATUS error 'STATUS_CONTROL_C_EXIT'(0xC000013A) on Windows, it is expected when console window closed or Ctrl+C pressed.
Now focus would not be automatically released on widget destruction, allowing unspecified order of widget destruction being safly with no-op.
Mutal exclusion locking overhead is significant(about 5x lag) in current implementation on MinGW32 for both 'YCLib' input and 'Helper' rendering.
	Actually both cases cause lag similarly when in-thread message loop delay (currently in shell input handler) is removed:
		1. About 55~80 kHz(faked as kFPS) can be achieved after removal the loop delay (but ususlly lower than 70 kHz), and about 480~560 kHz after removal of locking for both cases. Only 170~240 kHz can be achieved after removal of input locking.
		2. In July, 2012 it could be at a peak of greater than 730 kHz. It is believed that the improvement of functionality has effect on this, though still not clear which part cause the overhead.
		3. Intel VTune Amplifier XE 2013 detects seconds of spin time before the removal of locking (for an about 10 second run) and almost none (0.010s) after the removal. The use of hardware concurrency is "idle" before and "poor" after.
	No simple way to improve:
		1. No lock-free swap primative supported by std::atomic directly because almost no hardware support: http://stackoverflow.com/questions/15460829/lock-free-swap-of-two-unique-ptrt .
		2. Not only pointers themselves, content pointed should be thread-safe.
		3. Fine-grained thread-safe access should be remained anyway.
		4. If code in contexts like 'InputManager' uses coarse-grained concurrency, user should be cautious for synchronization. It is error-prone (even if easy).

todo.deferred:
Handling FreeType error 0x26: "no charmap" and 0x40: "out of memory"(descriptions from "fterrdef.h").
Ability for selecting specific typefaces with such glyphs.
Native exceptions should be caught at proper boundary.

note.merge:
(FTGL, GLFW, FMOD) @ !DS: considerable, shelved.
Cairo: rejected.
	Reason from http://people.mozilla.com/~roc/Samsung/Mozilla2DGraphics.pdf .

$2013-08:

report.impl:
The YSLib project now prefers using alias declarations over typedef declarations. Here's the rationale:
	1. The YSLib is try to use more ISO C++11 features aggresively when proper. Using aliases relax the complexity of many declarations, and reflects a kind of commonly accepted more natural syntax style, since the type name and identifier declared are separated clearly.
	2. A typedef declaration can introduce more than one identifier but an alias declaration cannot. However, this can easily misleads the reader so really rarely being used, and never appears in the YSLib project.
	3. Typedef declaration of an anonymous class has no equivalent alias declaration form, but it is also less commonly used in modern C++ (but not in C), and the YSLib project now deprecates this usage.
	4. There should be nothing different in general in other aspects. Though the current standard text is still using 'typedef', and for an implementation of both pre-C++11/C++11, keeping 'typedef' would save some '#ifdef' text, the YSLib project has no similar requirements.
	5. See https://groups.google.com/a/isocpp.org/forum/#!searchin/std-discussion/typedef/std-discussion/cwZ8HYQxxlM/Zzj4CTxSaskJ for the discussion of flavor in the ISO C++ standard text. No problems found for others even for using in standard proposals.
There is nothing cannot be implemented by ISO C++14 lambda expressions which is able via std::bind, see http://stackoverflow.com/questions/17363003/why-use-stdbind-over-lambdas-in-c14 .
For std::bind, pointers and reference wrappers arguments are almost always significant except for member function of a class type lvalue, 'std::ref(*this)' and 'this' is the same, while the YSLib code always preferred the latter(simpler). Note the difference is always significant for 'ystdex::any_iterator'.
For 32bpp '::HBITMAP', it seems that no pitch should be considered, i.e. the storage of pixels is contiguous.
Note that '::HBITMAP' data is raw bitmap compatible but not strict '::RGBQUAD', so the reserved 'rgbReserved' member can be used as alpha value.
It is believed that the data structure of input handling can hardly be modified by user code to adapt extended devices some platforms:
	For example, DS has no extended virtual key bit to differentiate more than one touch key. It is difficult for user to simulate this feature like high-level cursor event by design.
	So there is no need to always check the input is being with single key touched. This can be used at optimization of common GUI input state handling, etc.

dep.merge:
df.operators(https://github.com/d-frey/operators): considerable, shelved.

$2013-09:

report.impl:
The member function like 'std::string::c_str' cannot be wrapped in a function/function template because it returns temporary value.
Algorithm of circle rasterization in "http://cg.sjtu.edu.cn/lecture_site/chap2/mainframe224.htm" is wrong unless the circle is very small.
The type 'platform::Color' in module YCLib::Video of platform DS and MinGW32 is now comparable since it is implemented as an alias of class type which has an conversion function to integer type.
MSVC provides '__declspec(novtable)' for classes to ignore vfptr initialization in constructor and destructor as optimization. There are several conclusions:
	1. This is an optimization primarily for size, firstly appeared at VC++ 5.0, see http://msdn.microsoft.com/en-us/magazine/cc301398.aspx .
	2. Some major implementations like G++ seem to have no equivalence currently.
	3. This should be only used with most derived class object, otherwise the behavior is undefined. See http://msdn.microsoft.com/en-us/library/k13k85ky.aspx . It is fit for interface types.
	4. This would made behavior of code in constructor of derived classes non-confoming to ISO C++ if any 'novtable' base class virtural function is called or RTTI is used. See http://stackoverflow.com/questions/1801258/does-using-declspecnovtable-on-abstract-base-classes-affect-rtti-in-any-way .
	5. '__declspec(novtable)' should be wrapped by YBase.
	6. It is not fit for every interface type in YFramework as default option. It is reasonable for some specific interface types which have furthur constraints.

$2013-10:

report.impl:
Host renderer on adjusting boundary of host windows:
	Since b448, the full validation is forced to keep the boundary of host window steady.
	The content would still be trembling on resizing by dragging the boundary.
	This effect is of about the same quality of resizing on a normal application window (e.g. Windows Explorer window).
	Note that several windows of application (e.g. the image and chat windows of Tencent QQ 2013, main window of Xunlei 7.9) seem to be using other way which can still cause the boundary itself be trembling on resizing. This is similar (or even worse) to previous revisions of YFamework.
The std::basic_string of current libstdc++ is still non-conforming to ISO C++11 which disallows use of reference counting/copy-on-write implementation due to ABI compatibility.
	See $ref b449 "libstdc++ std::basic_string conformance" for references.
	Using of libstdc++ vstring is proper if strict conformance is really needed.
		See $ref b449 "libstdc++ vstring" for references.
For type parameter of function template as generic algorithms or initialization of specific types like instances of std::function, there are several considerable factors to determine what form of parameter type should be used:
	1. For general cases, rvalue reference of type parameter should be used to enable move semantics/perfect forwarding as possible, except below.
	2. For algorithms accepting iterators, functor or smart pointer types, non-reference type parameters are preferred to explicitly make the interface has call-by-value(copy) semantics for parameters. If needed call-by-reference semantics, std::ref can be used. This is also consistent with interface of corresponding parts of the standard library(i.e. iterator libraries/algorithms libraries/callable wrappers).
	3. For some other function templates which has no obvious call-by-value semantics, do not use type parameter directly. Then think twice of lvalue-reference or rvalue-reference type parameters.
	4. It is OK for rvalue-reference type parameters used for general templates with large categroies(like "all input iterator types" or "all callable types"), because there are no obvious requirements of call-by-value semantics.
	5. It is also OK for some callable proxies like asynchronous handlers to have non-call-by-value semantics of the callable parameters types, like some other parts of interface of the standard library(e.g. constructor of std::thread) .
Use member initializers properly to eliminite need of initialization in constructor as possible unless the initializer is intended to be the implementation details or some internal interface which should not be depend on by users.
There is a bug about template parameter declaration of Clang++ 3.4, up to 2013-10-21:
	The template parameter declaration 'bool = {}' should be accecpted, because it can be reduced as: template-parameter → parameter-declaration → decl-specifier-seq declarator = initializer-clause, with initializer-clause is '{}'.
	However, Clang++ rejects this code wrongly, though 'bool = false' can be accepted.
	Actually this code is in the parameter-declaration-list of declaration of class template ystdex::bitseg_iterator in YStandard::Iterator.
	Because currently Clang++ is not formally supported as the available compiler to build YSLib, the workaround above is not adopted.

todo.deferred:
Wrapping '__declspec(novtable)' when '_MSC_VER >= 1100'.

dep.merge:
libmagic(https://github.com/glensc/file): rejected.
	This library implements a DSL(with BNF provided among the source files) for querying magic number database. It is heavyweight and too complex for freestanding implementations.
	Stripping the code of extended functionality(other than MIME detection needed by YFramework) out is difficult, because functions for printing and parameters for state passing are spread in the call graph deeply.
	For hosted implementations, operation system or desktop environment based implementations may provide alternative more benifical interfaces for integrating custom/user-specified information of content types.
	Also the depolying overhead of the magic databace files is significant.
	For these reasons, this library is not suitable for YFramework, though may be fit for the low level indirect implentation esp. on POSIX systems.

$2013-11:

report.impl:
Marco '_GLIBCXX_DEBUG' should be removed as default, even in debug configuration.
	The standard libray debugging interface introduced by macro '_GLIBCXX_DEBUG' of libstdc++ may be incompatible with libraries not built with this macro.
	Though YSLib libraries are built with debug-aware configuration, currently the dependent libraries are not.
	This particularly has effect on libFreeImage.a, which uses containers of C++ standard library internally. The instantialized template class across libraries are not the same, and not guaranteed to be binary compatible.
		This would cause some functions of YSLib::Adaptor::Image go wrong.
	Alternatively, if the debug interface of libstdc++ is needed, namespace 'std::__debug' can be explicitly used.
	Removed such debug interface can also lead to smaller binaries and a little more runtime performance for debug configurations.
The bug of 'bool = {}' is same to Visual C++ 2013 as Clang++ 3.4(see $2013-10 report.impl).
ISO required 'std::FILE*' as an object type. Different to C++, (possible cv-qualified) void is object type.
	There exists actual C implementation with cv-void as 'std::FILE*'. For example, in the standard header from the CeGCC project it is 'void'.
Notes for disabling some VC++ warning:
	Used project configuration (for YFramework) but not '#pragma' for clean code and making users have choice to decide further.
	C4520 warns about multiple constructors found for the same class.
		It would wrongly detect the situation of exactly one non-template default constructor and one default constructor template, which should be well-formed and safe.
	C4800 warns about coercion to 'bool' type.
		It is marked as a "performance warning" by MSDN, though the performance decrease almost never happened for modern C++ code with reasonable C++ implementation in reality. It might be useful for finding the (bad-style) mix use of built-in 'bool' and 'BOOL' or other integral types.
		MSDN also says it is by design to treat cast as same as coercion here. Keeping the solution recommended by adding '!= 0' effectively make code lengthy with actually no benifit, thus it simply not fit for modern C++ in most cases.
		In C++ (but not in C), coercion or cast to 'bool' is quite safe. Comparaing to null pointer value explicitly is OK, but not required. On the contrast, it might be standard way to test null pointer (but not compare to zero), particular in the ISO C++11 wording "contextually convertible to bool" as some requirements for types including pointers.
		Too bad copying '!= 0' or similar mouthy stuff ('!= nullptr') everywhere in C++ code.
The workaround of move constructor and %operator= for Visual C++ 2013 is currently some slower than it should be with fully supported ISO C++11 implementation, because the 'noexcept' operator is missing, and no throwing specification is not guaranteed to work everywhere.

$2013-12:

report.impl:
The reference-counted 'std::basic_string' implementation in libstdc++ is still not conforming to ISO C++11.
	See $2013-10 report.impl.
	See $ref b449 "libstdc++ std::basic_string conformance" for references.
	Though ABI has changed before, the string implementation is not included, and even other breaking changes like 'std::list::size' implementation are reverted: http://gcc.gnu.org/wiki/Cxx11AbiCompatibility .
	It seems that the ABI would not switched in near future, or at early as of GCC 4.9: http://gcc.gnu.org/bugzilla/show_bug.cgi?id=56166 .
	Use libstdc++ '__gnu_cxx::__versa_string' from <ext/vstring.h> instead, if necessary.
		See $2013-10 report.impl.
		See $ref b449 "libstdc++ vstring" for references.
		Note no 'std::stringstream' counterpart, see: http://gcc.gnu.org/bugzilla/show_bug.cgi?id=56166#c4 .
		Be cautious to performace decrese: http://gcc.gnu.org/bugzilla/show_bug.cgi?id=54393 .

////

