Milo的ex-Hippocampus

从比并 JSON 库谈开源意义

Sun, 11 Sep 2016 00:00:00 +0000

在开发 RapidJSON 期间，我建立了另一开源项目 nativejson-benchmark，至今已整合 41 个 C/C++ JSON 开源库，评测它们对标准符合程度以及性能。本文先谈一下评测结果，再谈这个项目的意义。

评测方法

标准符合程度（conformance）：

使用 JSON_checker 判断是否能分辨正确及错误的 JSON（parse validation）。
解析字符串类型 JSON，如正确结果比对（parse string）。
解析数字类型 JSON，如正确结果比对（parse double）。
生成 DOM，再用 DOM 生成 JSON。判断来回往返（roundtrip）的字符串是否相同。

有些库可能没有生成 JSON 的功能，那么就不能完成来回往返检测。

性能检测：

解析 JSON 至 DOM（parse）。
把 DOM 转换至 JSON（stringify）。
美化转换（prettify）。
遍历 DOM 统计各种 JSON 类型的数量及字符串长度（statistics）。
使用 SAX 做来回往返（sax roundtrip）。
使用 SAX 做统计 (sax statistics)。
生成一个程序，检测可执行档的大小。该程序能解析 JSON 至 DOM 并把统计结果打印出来。

现时有 3 个性能测试用的 JSON，合共大小是 4.6MB。

加入此评测的库，最低限度要能实现 parse 和 statistics。其他检测是可选的。

结果

以下是 2016 年 9 月 9 日，在 MacBook Pro (Retina, 15-inch, Mid 2015, Corei7-4980HQ 2.80GHz)、clang 7.0 64-bit 的执行结果。也可用互动版本观看。

综合标准符合程度（越高越好）：

目前只有 RapidJSON 的全精度版本及 The Art of C++ / JSON (taocpp/json) 能获得 100% 完美得分。

其实这个检测中，部分数字解析及相关的来回往返测试是过于严格的，超越了标准所需的程度。有大约 80%-90% 已经可以说完全符合标准。之后会调整检测，把一些不属于标准必须的部分仅作参考，不算进整体分数。

有些库未能处理 ‘“\u0000”’ 和代理对（surrogate pair），尚可接受。有些库连 "\n" 这类转义符都不处理，就有点太过分了。

另一个常见问题是，一个 JSON 值结束后只能含有空白字符，例如[1, 2, 3] excited就是不合法的。有些库没做这个检测。

解析时间（越低越好）：

前排是 RapidJSON、gason、ujson4c、sajson。然而，后三者的标准符合程度都较低。现时最快的 RapidJSON 以 7.9ms 解析 4.6MB 的 JSON 文本，比最后一名快 140 倍以上。

解析后的内存分配大小（越低越好）：

Qt 未能成功检测其内存消耗，请忽略。RapidJSON 暂无对手，它在 x64 架构下的内存总消耗是 (JSON 节点数量 ✕ 16 字节 + 长字符串字节大小)。长字符串是指超过 13 个字节的字符串。之前发现了一个比 RapidJSON 更省的 jbson，但因为在 travis 上崩溃暂未加进评测。

Stringify 和 Prettify 时间（越低越好）：

这两项都是 RapidJSON 完胜。这里有一个问题是测试的 JSON 数据中，最大的一个主要内容全为浮点数，而这类型的生成也是各类型中最耗时的，也许将来要再调整测试数据。

代码大小（越低越好）：

由于要使用 V8 的 VM 来使用其 JSON 功能，所以执行文件特别大（静态链接）。较前排的 Folly、Qt、C++ REST SDK 都是使用动态链接的，所以特别小，其他的都是静态链接。而在静态链接库中，通常以 C 编写的较小，C++ 的较大。

起源

最初开发 RapidJSON 时，在项目内部写了一个性能测试，与 YAJL 和 JsonCpp 比较性能，仅量度耗时。然而，耗时并不是唯一需要量度的数值，也许一些库很快，却没有做各种处理，或是数字的转换方式并不精确。另外，要把各个其他 JSON 库加入 RapidJSON 的代码库中，也对使用者造成不便。

因此，后来就把那个性能测试独立成项目，制定了一个通用接口，每个库都只需实现该接口，便能作出各项检测，最后生成图表。

为了简化编译过程，整合大部分较简单的 JSON 库的时候，都是在测试 .cpp 中直接 #include 该库的 .cpp 实现。这样也确保编译参数都完全相同。只有像 Qt、V8、C++ Rest SDK 等需要自行安装。

学习

在整合这几十个库的同时，我也会参考他们的功能、API 设计、实现技术等等。遇到性能优良的库，也会仔细看看它有没有用到什么特别的技术。同时也会在想，有哪些功能都是缺乏的，了解更广，方能创新。

另一方面，我相信其他开发者也会通过这个平台，查看自己的库的优缺点，学习其他库并作出改进。当然，除了这种暗地里互相学习的，也有讨论交流的。

贡献

在建立这个项目以来，通常是被动地从 JSON 库的作者里接收 Pull Request，也许一些 JSON 库的作者也不知道有这个项目。

这个项目的目的，除了给予使用者一个参考，也希望能提升各个库的品质。没有一个库是完美的，需求各自不同。如果能提升品质，对它的使用者也有帮助。

因此，我最近为每个库的标准符合程度检测生成 markdown 格式的报告，并主动地发送成各个项目的 issue ，供他们参考。这个举动已获得不少回应，有些作者已积极修改一些问题。

另外，我之前整合遇到一些问题时，也会发 issue 查询讨论。例如，最近一轮的排查中，发现 facebook/folly 的 toJson() 异常地慢：

经性能分析后，发现问题仅在于一行代码：

// json.cpp
void escapeString(
    StringPiece input,
    std::string& out,
    const serialization_opts& opts) {
  auto hexDigit = [] (int c) -> char {
    return c < 10 ? c + '0' : c - 10 + 'a';
  };

  out.reserve(out.size() + input.size() + 2); // <-- 这一行
  out.push_back('\"');
  // ...

此行原来的意义，应该是希望预分配字符串的输出缓冲，避免过程中需要重新分配。但在一般的实现中，std::string::reserve() 在空间不足时，会把缓冲设置为指明的大小。由于每次的分配都是刚好够用而已，下次再输出字符串就必会再重新分配，造成 $O(n^2)$ 的性能瓶颈。而如果只是用 std::string::push_back()，它分配新空间会为现有大小的两倍（或其他倍数），达至分摊 $O(n)$ 的时间复杂度。所以，经过实验，只要删去该行，就能达到正常的性能：

这个测试显示消耗时 1928ms ➔ 29ms，我已提供 issue 及 PR。

后语

JSON 的处理工作对于一些后台服务、嵌入式系统来说，可能是一个很重要的部分，影响整体性能。虽然现时我的工作其实并没怎么能用到这些功能，我仍然觉得，开发 RapidJSON 及这个评测项目对于我个人、公司及开源社区也是有帮助的。

我会持续更进这些项目。之前还希望加入其他原生库，例如是 Objective C、Go、Rust 写成的库，如果有熟悉这方面的同学，欢迎与我联系。

有鉴于看过这么多 JSON 库，最近也写了一个极简的 C JSON 库，希望用它来写几篇入门级的《从零开发一个 JSON 库》，供刚学过编程的大学同学阅读，请各位支持。

RapidJSON v1.1.0 发布简介

Sat, 27 Aug 2016 00:00:00 +0000

时隔 15.6 个月，终于发布了一个新版本 v1.1.0。

新版本除了包含了这些日子收集到的无数的小改进及 bug fixes，也有一些新功能。本文尝试从使用者的角度，简单介绍一下这些功能和沿由。

JSON Pointer

也许 RapidJSON 一直最为人垢病的地方，是它奇怪的 API 设计。例如，对 DOM 加添数据要给于 allocator 参数：

#include "rapidjson/document.h"

using namespace rapidjson;

// ...

Document d(kObjectType);

Value a(kArrayType);
for (int i = 1; i <= 4; i++)
    a.PushBack(i, d.GetAllocator());

d.AddMember("a", a, d.GetAllocator());

// { a : [1, 2, 3, 4] }

这是由于 RapidJSON 的 DOM 使用局部的分配器，以避免全局分配器的问题。而为了节省内存，每个 Value 不会存储分配器的指针，所以必须从外部提供。

此设计也导致另一种问题。我们看看一个例子，使用 DOM API 访问以下这个 JSON：

{
    "widget": {
        "window": {
            "title": "Sample Konfabulator Widget"
        }
    }
}

要访问 title，最直觉想到的应该是这样：

Document d;
d.Parse(json);
std::cout << d["widget"]["window"]["title"].GetString();

如果 widget、window 或 title 不存在呢？以标准库 std::map::operator[] 的做法来说，当找不到键，它会自动加入一个键值对，并返回该值（所以 map::operator[] 必须是 non-const 函数）。然而，RapidJSON 创建值的时候需要 allocator，所以不可能自动加入键值对。因此，RapidJSON 规定以 operator[] 访问时，必须确保键存在（找不到时直接断言失败）。若不能确保，应先用 HasMember() 判断，或更好的是使用 FindMember()，因为它可以告之键是否存在的同时，能通过迭代器取得该值。可是，使用 FindMember() 去访问多层对象，代码非常冗长：

Value::ConstMemberIterator itr1 = d.FindMember("widget");
if (itr1 != d.MemberEnd()) {
    const Value& widget = itr1->value;
    if (widget.IsObject()) {
        Value::ConstMemberIterator itr2 = widget.FindMember("window");
        if (itr2 != widget.MemberEnd()) {
            const Value& window = itr2->value;
            if (window.IsObject()) {
                Value::ConstMemberIterator itr3 = window.FindMember("title");
                if (itr3 != window.MemberEnd()) {
                    const Value& title = itr3->value;
                    if (title.IsString()) {
                        std::cout << title.GetString();
                    }
                }
            }
        }
    }
}

这坨代码也许是最快最直接的方式。但一般业务代码写成这样，可读性太低，也容易出错。

大家都可以写一些辅助函数来解决这个问题。而我选择了实现 RFC6901 ── JSON Pointer。先看看使用后的结果：

#include "rapidjson/pointer.h"

// ...

if (const Value* title = GetValueByPointer(d, "/widget/window/title")) {
    if (title->IsString()) {
        std::cout << title->GetString();
    }
}

这个版本简单得多吧，"/widget/window/title" 是一个 JSON Pointer 的字符串形式，然后 GetValueByPointer() 在 d 上解引用，如果失败就返回空指针。

在逻辑上是和上面的冗长版本是一模一样的，只是增加了一些解析 JSON Pointer 的运行时间及空间成本。对大多数人来说，应该更会接受这个版本。

有时候，业务逻辑还会是这样的：「如果键不存在，就使用缺省值。」RapidJSON 的 JSON Pointer 也提供此功能：

Value& title = GetValueByPointerWithDefault(
    d, "/widget/window/title", "untitled");

当解引用失败时，它会创建整个路径，并把预设值复制成新值，并返回该值。由于它总能返回一个值，此函数的返回类型为引用而不是指针。

在此也简单介绍一下 JSON Pointer 的语法。它以 ‘/’ 分隔多个 token，而每个 token 可以是 JSON object 的键，也可以是 JSON array 的下标。还有一种特殊 token 是负号 -，它可以指 JSON array 最后元素的下一个元素。使用这种特性能实现 PushBack() 的效果：

Document d;
CreateValueByPointer(d, "/a").SetArray();

for (int i = 1; i <= 4; i++)
    SetValueByPointer(d, "/a/-", i);

// { a : [1, 2, 3, 4] }

使用 JSON Pointer 的另一优点在于，它本身也是一个字符串，可以放置在 JSON 或其他文本格式之中。那么，我们便有一个标准方式去引用 JSON 中的值。

希望 JSON Pointer 能减轻使用者的负担，同时也提供一种数据驱动的弹性。新功能 JSON Pointer 简单介绍至此，更多信息可参考 RapidJSON 使用手册：Pointer。

JSON Schema

上面我们也谈到一个问题，JSON 里的组织方式、类型可能和预期的不同，我们可能要写很多代码去校验一个 JSON 的格式是否乎合预期。特别是后台服务器可能接收到不正常的JSON，甚至是恶意编写的 JSON 以图攻击。

在 XML 的世界中，可使用 XML DTD 或 XML Schema 去描述 XML 的结构。在 JSON 的世界中，已经有相关草案，称为 JSON Schema。

RapidJSON 实现了 JSON Schema v4 draft，并正式纳入了 v1.1.0。先看看用法：

#include "rapidjson/schema.h"
// ...
Document sd;
if (!sd.Parse(schemaJson).HasParseError()) {
    // 此 schema 不是合法的 JSON
}
SchemaDocument schema(sd); // 把一个 Document 编译至 SchemaDocument
// 之后不再需要 sd
Document d;
if (!d.Parse(inputJson).HasParseError()) {
    // 输入不是一个合法的 JSON
}
SchemaValidator validator(schema);
if (!d.Accept(validator)) {
    // 输入的 JSON 不合乎 schema
}

以我所知，现时所有 JSON Schema 实现都是校验一个 DOM 是否合乎 Schema。RapidJSON 做了一个创新的尝试，以事件流（SAX 风格）的方式去做校验。上面的例子利用 Document::Accept() 产生事件流，然后送交 SchemaValidator 校验。也许读者会问：「这也是在校验一个 DOM 是否合乎 Schema，有什么特别吗？」

这实际意味着，RapidJSON 的 JSON Schema 校验器除了可以校验 DOM，也可以校验更底层的 SAX。例如，我们可以用 SAX 解析 JSON 时，同时进行 JSON Schema 校验。如果中途不合乎 JSON Schema，就能直接中止解析。

SchemaValidator validator(schema);
Reader reader;
if (!reader.Parse(stream, validator)) {
    if (!validator.IsValid()) {
        // 输入的 JSON 不合乎 schema
    }
}

也可以同时把事件转发至一个自定义 handler：

MyHandler handler;
GenericSchemaValidator<SchemaDocument, MyHandler> validator(schema, handler);
Reader reader;
if (!reader.Parse(stream, validator)) {
    if (!validator.IsValid()) {
        // 输入的 JSON 不合乎 schema
    }
}

由于 DOM 解析 JSON 时，底层也是使用 SAX，所以也可以同时做 Schema 校验。其实除了解析，在生成时也可以进行校验，以确保输出的 JSON 也是乎合 Schema 的。这些用法都可参考 RapidJSON 使用手册：Schema。要学习 JSON Schema 的写法，笔者推荐 Understanding JSON Schema 这个英文网站。

C++11 范围 for 循环

此版本还加入了 Array 和 Object 辅助类型（包裹类），可分别通过 Value::GetArray()、Value::GetObject() 获取。这两个辅助类型提供该 JSON 类型专门的接口，例如 Array::PushBack()、Object::AddMember() 等。更重要的是，为了令 C++11 用户使用得更顺手，它们可做范围 for 循环（range-based for loop）：

// C++03
for (Value::ConstValueIterator itr = a.Begin(); itr != a.End(); ++itr)
    printf("%d ", itr->GetInt());

// C++11
for (auto& v : a.GetArray())
    printf("%d ", v.GetInt());

// C++03
for (Value::ConstMemberIterator itr = document.MemberBegin();
    itr != document.MemberEnd(); ++itr)
{
    printf("Type of member %s is %s\n",
        itr->name.GetString(), kTypeNames[itr->value.GetType()]);
}

// C++11
for (auto& m : document.GetObject())
    printf("Type of member %s is %s\n",
        m.name.GetString(), kTypeNames[m.value.GetType()]);

其他相关详情可参阅 RapidJSON 使用手册：教程。

结语

这个 RapidJSON 版本对我而言是一个挑战。

JSON Schema 实际上也需要 JSON Pointer，所以 JSON Pointer 可算是一举两得的新功能。但实现 JSON Schema 时有两个难点。一个是 JSON Schema 需要正则引擎，在 C++11 下能直接使用 std::regex；而为了 C++03，我还实现了一个 500 行代码的 Thompson NFA 正则引擎。另一个难点在于，事件流的校验不容易实现 allOf、anyOf、oneOf、not 等关键字，需要多个校验器同时检验事件流。

新功能 JSON Schema 和 JSON Pointer 都是附加功能，完全不影响 v1.0.x 的 API。

除新功能外，此版本含有一个重要的内存优化。在 x86-64 架构下，64 位指针只使用到 48 位，我重新设计了 Value 的排布，使每个值的内存开销从 24 字节缩减至 16 字节。虽然存储指针时会有时间开销，但因大量缩减内存，更好的缓存一致性应该可以厘补损失，甚至能进一步提升整体性能。

屈指一算，RapidJSON 已快近 5 个年头了，最近一年我转部门后，更少机会在工作上使用 RapidJSON，所以我可能较少机会发现问题和新需求。虽然是这样，我仍然会继续维护这个项目，也要靠大家去发现问题和新需求，希望能得到大家的意见。

P.S. 可能大家会关心性能，我会尽快更新 nativejson-benchmark。

RapidJSON 代码剖析（四）：优化 Grisu

Tue, 30 Jun 2015 00:00:00 +0000

我曾经在知乎的一个答案里谈及到 V8 引擎里实现了 Grisu 算法，我先引用该文的内容简单介绍 Grisu。然后，再谈及 RapidJSON 对它做了的几个底层优化。

Grisu是什么

Grisu 是把浮点数转换为字符串的算法。在 Chrome 里执行这段 JavaScript 实际上就调用了 Grisu：

document.write(1/3); // 0.3333333333333333

这个问题看似简单，实际上是很复杂的事情。

在1980年之前，许多 C 语言标准库中的 printf() 都会产生「不正确」的结果。Coonen 在那时候做了相关的博士研究[1]，但并没有受到广泛的知悉和应用。1990年 Steele 等人发表了名为 Dragon4 的算法[2]，通过使用大数运算来确保精确的转换。而这个算法应用在大部分 C 程序语言库的 printf()，以及其他用 printf() 来实现这功能的语言之中。

这样就20年过去，虽然中间有一些小改进[3][4]，但基本的思路仍然是这样。到了2010年，Loitsch 发表了 Grisu 算法[5]，而 V8 也实现了这个算法。

该篇文章阐述了3个算法，分别是原始的 Grisu，及其改进版 Grisu2 和 Grisu3。Grisu 算法比 Dragon4 等算法优越的地方就是一个字──快。以下简单介绍一下它们的特点。

首先，什么是「正确」的转换？其定义是，一个浮点数转换成的十进位字符串之后，该字符串可以完美的转换回去原来的浮点数，如果用C语言来描述的话：

// 除 +/-inf 及 NaN 外的浮点数都应该传回 true。
bool Verify(double d) {
    assert(!isnan(d) && !isinf(d));
    char buffer[32]; // 足够大么？
    dtoa(buffer, d); // 双精度浮点数转换至字符串，是double-to-ascii
    char* end;
    double d2 = strtod(buffer, &end); // 字符串转换至双精度浮点数
    return *end == '\0' && d == d2;
}

如前所述，Dragon4 使用大数运算，还涉及动态内存分配（你知道printf()里可能会做malloc()么？）。而 Grisu 则不需要，只需要用到64位整数运算便可以实现转换！所以那篇文章题目就以 “… with integers” 作结尾。

Grisu 的算法非常简单，但它有一个缺点，就是其结果并不像是给人看的。如文中的例子，Grisu 把 0.3 的打印成 29999999999999998e-17。这是「正确的」转换结果，它可以通过 Verify() 验证。

虽然该算法非常快，但一般人大概不会接受这样的结果。作者也因此研发出改进版本 Grisu2，在使用64位整数实现 double 的转换时，可以利用额外的 64 - 53 = 11 位去缩减转换的结果（53 为 double 的尾数位数）。Grisu2 可以把 >99.9% 的浮点数转换成最短的「正确」字符串，其馀<0.1%的浮点数仍然是「正确」的，但不是最短的答案。

也许一般人就见好就收了，毕竟已证明算法的正确性，只是有那么 <0.1% 情况未达至最完美的结果。不过该作者还是继续研究出 Grisu3。Grisu3 并不能解决那一小撮麻烦制造者，但它能在计算期间侦查到哪些 double 在这算法中未能得出最优的结果。既然办事快捷的小部门搞不定，就可以把它交给 Dragon4 或其他较慢的算法。

V8 里实现了 Grisu3 以及大整数的算法（我不肯定是Dragon4还是其他），后来Google也把它分离成为一个独立的C++程序库double-conversion。

为了优化 RapidJSON 的浮点数转换，也由于 RapidJSON 是仅需头文件的 JSON 库，我就按 Loitsch 的实现编写了一个 Grisu2 的头文件库，可以在 dtoa-benchmark，那里还比较了多个 dtoa() 实现的性能。因为 Grisu3 需要另一个更庞大的大数实现，而暂时 RapidJSON 不需要最优结果，所以就仅实现了一个性能更好及更简短的 Grisu2。

测试不同算法／实现下的性能（VC2013 64-bit），fpconv、grisu2、milo 都是 Grisu2 的实现，doubleconv 是 V8 的 Grisu3 实现。milo 对 sprintf 的加速比约是 9x。

加入了经优化的 Grisu2 之后，RapidJSON 的 JSON 字符串化（stringify）性能远超其他 JSON 库。

整数除法优化

在原始论文[5] Grisu2 的digit_gen()函数（对应于 double-conversion 实现中的DigitGen()）中，有一段代码是用于生成足够的十进位数位：

uint32_t p1 = /*...*/;
int kappa = 10;
uint32_t div = 1000000000;
while (kappa > 0) {
    d = p1 / div; // 第一个除法
    if (d || *len)
        buffer[(*len)++] = static_cast<char>('0' + static_cast<char>(d));
    p1 %= div;
    kappa--;
    div /= 10;    // 第二个除法
    // ...
}

在性能剖析时，我发现这段代码的32位无号整数除法成为一个瓶颈。

翻查一下资料[6]，Intel Haswell 架构的 DIV 32位除法指令的延迟（latency）是 28 个周期，吞吐率是 10 个周期。作为比较，同一架构下 MUL 32位乘法指令的延迟只是 4 个周期，吞吐率只是半个周期。

在许多书籍（如[7]）也会谈及，当除数为常数时，可以把除法变成乘以除数的倒数。现在的编译器都会自动做这个优化。事实上，在上面的代码里，第二个除法（div /= 10）中的除数（10）就是常数，编译器会自动把它优化成64位乘法及右移指令，例如 clang 在 x86-64 目标下：

mov    esi, 0xcccccccd  ; 3435973837
imul   rsi, rax
shr    rsi, 0x23        ; 35

注意到 $3435973837 \cdot 2^{-35} = 0.10000000000582076609134674072265625$，而这个精度足以应付任意32位无号整数除以10。

我们再分析原来的代码，会发现，其实除数 div 等于 $10^{\kappa - 1}$，我们可以使用常数除数令编译器进行上述的优化：

while (kappa > 0) {
    uint32_t d = 0;
    switch (kappa) {
        case  9: d = p1 /  100000000; p1 %=  100000000; break;
        case  8: d = p1 /   10000000; p1 %=   10000000; break;
        case  7: d = p1 /    1000000; p1 %=    1000000; break;
        case  6: d = p1 /     100000; p1 %=     100000; break;
        case  5: d = p1 /      10000; p1 %=      10000; break;
        case  4: d = p1 /       1000; p1 %=       1000; break;
        case  3: d = p1 /        100; p1 %=        100; break;
        case  2: d = p1 /         10; p1 %=         10; break;
        case  1: d = p1;              p1 =           0; break;
        default:;
    }
    if (d || *len)
        buffer[(*len)++] = static_cast<char>('0' + static_cast<char>(d));
    kappa--;
    // ...
}

这样的话，编译器就会把除法都变成乘法及右移。由于这个switch的 cases 是密集的，编译器也可使用 branch table 很好地优化它。不过缺点就是生成的机器码较原来多。

顺便一提，当整数模除运算（modulo operation）与除法成对出现时，而操作数相同，那么编译器会把模除运算生成一个乘法及减法：

$\begin{align*} c &= \left\lfloor a \mathbin{/} b \right\rfloor \\ r &= a - b \cdot c \end{align*}$

这一节没有使用 intrinsic 或其他底层优化，只是手动把除法用另一个方式表达，就能达到有效的性能提升。

底层优化

然而，为了进一步提升性能，RapidJSON 也会尽量针对编译器／目标平台做一些优化。

例如，在 Grisu 算法中，需要实现一个自定义的浮点数类型（DiyFp），这个类型的乘法需要使用到一个 64 位整数乘法，并获得 128 位结果，然后进行数值修约（rounding）。然而，标准 C++ 中并没有获得 128 位乘法结果的方法，因此[5]提供了一个通用实现方法：

struct DiyFp {
    DiyFp operator*(const DiyFp& rhs) const {
        const uint64_t M32 = 0xFFFFFFFF;
        const uint64_t a = f >> 32;
        const uint64_t b = f & M32;
        const uint64_t c = rhs.f >> 32;
        const uint64_t d = rhs.f & M32;
        const uint64_t ac = a * c;
        const uint64_t bc = b * c;
        const uint64_t ad = a * d;
        const uint64_t bd = b * d;
        uint64_t tmp = (bd >> 32) + (ad & M32) + (bc & M32);
        tmp += 1U << 31;  /// mult_round
        return DiyFp(ac + (ad >> 32) + (bc >> 32) + (tmp >> 32), e + rhs.e + 64);
    }
    // ...
    uint64_t f;
    int e;
};

上面的通用实现可用于支持32位乘法并获得64位结果的编译器。然而，在许多 64 位 CPU 架构下，64位乘数是可以获得128位结果的。我们可以针对各编译器，使用 intrinsic 或扩展类型来实现这个函数：

    DiyFp operator*(const DiyFp& rhs) const {
#if defined(_MSC_VER) && defined(_M_AMD64)
        uint64_t h;
        uint64_t l = _umul128(f, rhs.f, &h);
        if (l & (uint64_t(1) << 63)) // rounding
            h++;
        return DiyFp(h, e + rhs.e + 64);
#elif (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)) && defined(__x86_64__)
        __extension__ typedef unsigned __int128 uint128;
        uint128 p = static_cast<uint128>(f) * static_cast<uint128>(rhs.f);
        uint64_t h = static_cast<uint64_t>(p >> 64);
        uint64_t l = static_cast<uint64_t>(p);
        if (l & (uint64_t(1) << 63)) // rounding
            h++;
        return DiyFp(h, e + rhs.e + 64);
#else
        // 通用实现
#endif
    }

除此以外，这个 DiyFp 类型还要支持浮点数正规化（normalization）的操作，即把尾数（mantissa）的最高位变成 1（这个浮点数没有隐藏最高位）：

    DiyFp Normalize() const {
        DiyFp res = *this;
        while (!(res.f & (static_cast<uint64_t>(1) << 63))) {
            res.f <<= 1;
            res.e--;
        }
        return res;
    }

许多 CPU 也支持 Find first set 指令，执行一个指令便能扫瞄到最高为1的位：

    DiyFp Normalize() const {
#if defined(_MSC_VER) && defined(_M_AMD64)
        unsigned long index;
        _BitScanReverse64(&index, f);
        return DiyFp(f << (63 - index), e - (63 - index));
#elif defined(__GNUC__) && __GNUC__ >= 4
        int s = __builtin_clzll(f);
        return DiyFp(f << s, e - s);
#else
        // 通用实现
#endif
    }

由于 gcc/clang 的内置函数能对不同目标平台生成最优的代码，使用起来更为方便。

结语

由于篇幅的关系，本文并没有仔细地解释 Grisu 的算法，而我也不认为能比原文[5]更浅白地介绍当中的原理。本文只是谈到两个优化方式，一个是利用常数除数令编译器能进行优化，而另一种优化则是由于 C++ 标准无法使用一些 CPU 提供的功能，而要采用编译器或平台相关的优化方法。

参考文献

[1] Coonen, Jerome T. “an Implementation Guide to a Proposed Standard for Floating-Point Arithmetic.” Computer 13.1 (1980): 68-79.

[2] Steele Jr, Guy L., and Jon L. White. “How to print floating-point numbers accurately.” ACM SIGPLAN Notices. Vol. 25. No. 6. ACM, 1990. http://kurtstephens.com/files/p372-steele.pdf

[3] Gay, David M. “Correctly rounded binary-decimal and decimal-binary conversions.” Numerical Analysis Manuscript 90-10 (1990). http://ampl.com/REFS/rounding.pdf

[4] Burger, Robert G., and R. Kent Dybvig. “Printing floating-point numbers quickly and accurately.” ACM SIGPLAN Notices. Vol. 31. No. 5. ACM, 1996. http://www.cs.indiana.edu/~dyb/pubs/FP-Printing-PLDI96.pdf

[5] Loitsch, Florian. “Printing floating-point numbers quickly and accurately with integers.” ACM Sigplan Notices 45.6 (2010): 233-243. http://www.cs.tufts.edu/~nr/cs257/archive/florian-loitsch/printf.pdf

[6] Granlund, Torbjörn. “Instruction latencies and throughput for AMD and Intel x86 processors, 2014.” https://gmplib.org/~tege/x86-timing.pdf

[7] Warren, Henry S. Hacker’s delight. Pearson Education, 2012.

RapidJSON 代码剖析（三）：Unicode 的编码与解码

Wed, 03 Jun 2015 00:00:00 +0000

RapidJSON 希望尽量支持各种常用 UTF 编码，用四百多行代码实现了 5 种 Unicode 编码器／解码器，另外加上 ASCII 编码。

根据 RFC-7159：

8.1 Character Encoding

JSON text SHALL be encoded in UTF-8, UTF-16, or UTF-32. The default encoding is UTF-8, and JSON texts that are encoded in UTF-8 are interoperable in the sense that they will be read successfully by the maximum number of implementations; there are many implementations that cannot successfully read texts in other encodings (such as UTF-16 and UTF-32).

翻译：JSON文本应该以UTF-8、UTF-16、UTF-32编码。缺省编码为UTF-8，而且有大量的实现能读取以UTF-8编码的JSON文本，说明UTF-8具互操作性；有许多实现不能读取其他编码（如 UTF-16及UTF-32）

本文会简单介绍它的实现方式。

回顾 Unicode、UTF 与 C++

Unicode 是一个标准，用于处理世界上大部分的文字。在 Unicode 出现之前，每种语言文字会使用不同的编码，例如英文主要用 ASCII、中文主要用 GB 2312 和大五码、日文主要用 JIS 等等。这样会造成很多不便，例如一个文本信息很难混合各种语言的文字。

Unicode 定义了统一字符集（Universal Coded Character Set, UCS），每个字符映射至一个整数码点（code point），码点的范围是 0 至 0x10FFFF。储存这些码点有不同方式，这些方式称为 Unicode 转换格式（Uniform Transformation Format, UTF）。现时流行的 UTF 为 UTF-8、UTF-16 和 UTF-32。每种 UTF 会把一个码点储存为一至多个编码单元（code unit）。例如 UTF-8 的编码单元是 8 位的字节、UTF-16 为 16 位、UTF-32 为 32 位。除 UTF-32 外，UTF-8 和 UTF-16 都是可变长度编码。

UTF-8 成为现时互联网上最流行的格式，有几个原因：

它采用字节为编码单元，不会有字节序（endianness）的问题。
每个 ASCII 字符只需一个字节去储存。
如果程序原来是以字节方式储存字符，理论上不需要特别改动就能处理 UTF-8 的数据。

那么，在处理 JSON 时，若使用 UTF-8，我们为何还需要特别处理？这是因为 JSON 的字符串可以包含 \uXXXX 这种转义字符串。例如["\u20AC"]这个JSON是一个数组，里面有一个字符串，转义之后是欧元符号"€"。在 JSON 中，这个转义符使用 UTF-16 编码。JSON 也支持 UTF-16 代理对（surrogate pair），例如高音谱号(U+1D11E)可写成"\uD834\uDD1E“。所以，即使是 UTF-8 的 JSON，我们都需要在解析JSON字符串时做解码／编码工作。

虽然 Unicode 始于上世纪90年代，C++11 才加入较好的支持。RapidJSON 为了支持 C++ 03，需要自行实现一组编码／解码器。

Encoding

RapidJSON 的编码（encoding）的概念是这样的（非C++代码）：

concept Encoding {
    typename Ch;    //! Type of character. A "character" is actually a code unit in unicode's definition.

    enum { supportUnicode = 1 }; // or 0 if not supporting unicode

    //! \brief Encode a Unicode codepoint to an output stream.
    //! \param os Output stream.
    //! \param codepoint An unicode codepoint, ranging from 0x0 to 0x10FFFF inclusively.
    template<typename OutputStream>
    static void Encode(OutputStream& os, unsigned codepoint);

    //! \brief Decode a Unicode codepoint from an input stream.
    //! \param is Input stream.
    //! \param codepoint Output of the unicode codepoint.
    //! \return true if a valid codepoint can be decoded from the stream.
    template <typename InputStream>
    static bool Decode(InputStream& is, unsigned* codepoint);

    //! \brief Validate one Unicode codepoint from an encoded stream.
    //! \param is Input stream to obtain codepoint.
    //! \param os Output for copying one codepoint.
    //! \return true if it is valid.
    //! \note This function just validating and copying the codepoint without actually decode it.
    template <typename InputStream, typename OutputStream>
    static bool Validate(InputStream& is, OutputStream& os);

    // The following functions are deal with byte streams.

    //! Take a character from input byte stream, skip BOM if exist.
    template <typename InputByteStream>
    static CharType TakeBOM(InputByteStream& is);

    //! Take a character from input byte stream.
    template <typename InputByteStream>
    static Ch Take(InputByteStream& is);

    //! Put BOM to output byte stream.
    template <typename OutputByteStream>
    static void PutBOM(OutputByteStream& os);

    //! Put a character to output byte stream.
    template <typename OutputByteStream>
    static void Put(OutputByteStream& os, Ch c);
};

由于 C++ 可使用不同类型作为字符类型，如 char、wchar_t、char16_t (C++11)、char32_t (C++11)等，实现这个 Encoding 概念的类需要设定一个 Ch 类型。

这当中最种要的函数是 Encode() 和 Decode()，它们分别把码点编码至输出流，以及从输入流解码成码点。Validate()则是只验证编码是否正确，并复制至目标流，不做解码工作。例如 UTF-16 的编码／解码实现是：

template<typename CharType = wchar_t>
struct UTF16 {
    typedef CharType Ch;
    RAPIDJSON_STATIC_ASSERT(sizeof(Ch) >= 2);

    enum { supportUnicode = 1 };

    template<typename OutputStream>
    static void Encode(OutputStream& os, unsigned codepoint) {
        RAPIDJSON_STATIC_ASSERT(sizeof(typename OutputStream::Ch) >= 2);
        if (codepoint <= 0xFFFF) {
            RAPIDJSON_ASSERT(codepoint < 0xD800 || codepoint > 0xDFFF); // Code point itself cannot be surrogate pair 
            os.Put(static_cast<typename OutputStream::Ch>(codepoint));
        }
        else {
            RAPIDJSON_ASSERT(codepoint <= 0x10FFFF);
            unsigned v = codepoint - 0x10000;
            os.Put(static_cast<typename OutputStream::Ch>((v >> 10) | 0xD800));
            os.Put((v & 0x3FF) | 0xDC00);
        }
    }

    template <typename InputStream>
    static bool Decode(InputStream& is, unsigned* codepoint) {
        RAPIDJSON_STATIC_ASSERT(sizeof(typename InputStream::Ch) >= 2);
        Ch c = is.Take();
        if (c < 0xD800 || c > 0xDFFF) {
            *codepoint = c;
            return true;
        }
        else if (c <= 0xDBFF) {
            *codepoint = (c & 0x3FF) << 10;
            c = is.Take();
            *codepoint |= (c & 0x3FF);
            *codepoint += 0x10000;
            return c >= 0xDC00 && c <= 0xDFFF;
        }
        return false;
    }

    // ...
};

转码

RapidJSON 的解析器可以读入某种编码的JSON，并转码为另一种编码。例如我们可以解析一个 UTF-8 JSON文件至 UTF-16 的 DOM。我们可以实现一个类做这样的转码工作：

template<typename SourceEncoding, typename TargetEncoding>
struct Transcoder {
    //! Take one Unicode codepoint from source encoding, convert it to target encoding and put it to the output stream.
    template<typename InputStream, typename OutputStream>
    RAPIDJSON_FORCEINLINE static bool Transcode(InputStream& is, OutputStream& os) {
        unsigned codepoint;
        if (!SourceEncoding::Decode(is, &codepoint))
            return false;
        TargetEncoding::Encode(os, codepoint);
        return true;
    }

    // ...
};

这段代码非常简单，就是从输入流解码出一个码点，解码成功就编码并写入输出流。但如果来源的编码和目标的编码都一样，我们不是做了无用功么？但 C++ 的[模板偏特化（partial template specialization）可以这么做：

//! Specialization of Transcoder with same source and target encoding.
template<typename Encoding>
struct Transcoder<Encoding, Encoding> {
    template<typename InputStream, typename OutputStream>
    RAPIDJSON_FORCEINLINE static bool Transcode(InputStream& is, OutputStream& os) {
        os.Put(is.Take());  // Just copy one code unit. This semantic is different from primary template class.
        return true;
    }

    // ...
};

那么，不用转码的时候，就只需复制编码一个单元。零开销！所以，在解析及生成 JSON 时都使用到 Transcoder 去做编码转换。

UTF-8 解码与 DFA

在 UTF-8 中，一个码点可能会编码为1至4个编码单元（字节）。它的解码比较复杂。RapidJSON 参考了 Hoehrmann 的实现，使用确定有限状态自动机（deterministic finite automation, DFA）的方式去解码。UTF-8的解码过程可以表示为以下的DFA:

当中，每个转移（transition）代表在输入流中遇到的编码单元（字节）范围。这幅图忽略了不合法的范围，它们都会转移至一个错误的状态。

原来我希望在本文中详细解析 RapidJSON 实现中的「优化」。但几年前在 Windows 上的测试结果和近日在 Mac 上的测试结果大相迳庭。还是等待之后再分析后再讲。

AutoUTF

有时候，我们不能在编译期决定 JSON 采用了哪种编码。而上述的实现都是在编译期以模板类型做挷定的。所以，后来 RapidJSON 加入了一个运行时做动态挷定的编码类型，称为 AutoUTF。它之所以称为自动，是因为它还有检测字节顺序标记（byte-order mark, BOM）的功能。如果输入流有 BOM，就能自动选择适当的解码器。不过，因为在运行时挷定，就需要多一层间接。RapidJSON采用了函数指针的数组来做这间接层。

ASCII

有一个用家提出希望写入 JSON 时，能把所有非 ASCII 的字符都写成 \uXXXX 转义形式。解决方法就是加入了 ASCII 这个模板类：

template<typename CharType = char>
struct ASCII {
    typedef CharType Ch;

    enum { supportUnicode = 0 };

    // ...

    template <typename InputStream>
    static bool Decode(InputStream& is, unsigned* codepoint) {
        unsigned char c = static_cast<unsigned char>(is.Take());
        *codepoint = c;
        return c <= 0X7F;
    }

    // ...
};

通过检测 supportUnicode，写入 JSON 时就可以决定是否做转义。另外，Decode()时也会检查是否超出 ASCII 范围。

总结

RapidJSON 提供内置的 Unicode 支持，包括各种 UTF 格式及转码。这是其他 JSON 库较少做的部分。另外，RapidJSON 是在输入输出流的层面去处理，避免了把整个JSON读入、转码，然后才开始解析。RapidJSON 这么实现节省内存，而且性能应该更优。

最近为了开发 RapidJSON 下一个版本新增的 JSON Schema 功能，实现了一个正则表达式引擎。该引擎也利用了 Encoding 这套框架，轻松地实现了 Unicode 支持，例如可以直接匹配 UTF-8 的输入流。

RapidJSON 代码剖析（二）：使用 SSE4.2 优化字符串扫描

Wed, 20 May 2015 00:00:00 +0000

现在的 CPU 都提供了单指令流多数据流（single instruction multiple data, SIMD）指令集。最常见的是用于大量的浮点数计算，但其实也可以用在文字处理方面。其中，SSE4.2 包含了一些专为字符串而设的指令。我们通过使用这些指令，可以大幅提升某些 JSON 解析的性能。

跳过空白字符

我们知道，有一些 JSON 含有缩进（indentation），这些 JSON 有大量的空白字符（whitespace）。在解析 JSON 的时候，需要跳过这些空白字符。这个操作在 RapidJSON 下是这样的（reader.h，为配合版面稍改排版）：

template<typename InputStream>
void SkipWhitespace(InputStream& is) {
    internal::StreamLocalCopy<InputStream> copy(is);
    InputStream& s(copy.s);

    while (s.Peek() == ' '  ||
           s.Peek() == '\n' ||
           s.Peek() == '\r' ||
           s.Peek() == '\t')
    {
        s.Take();
    }
}

我们先不关注 StreamLocalCopy 等东西。这段代码很简单，就是凡在输入流中遇到4种空白字符，都提取出来跳过，直至流里的字符为非空白字符。

但这种代码会带来很多分支（branching），而且我们每次只能处理一个字符。

SSE4.2

在 Intel 的 SSE4.2 指令集中，有一个 pcmpistrm 指令，它可以一次对一组16个字符与另一组字符作比较，也就是说一个指令可以作最多16×16=256次比较。

对于上面跳过空白字符的需求，我们只需要对16个输入流里的字符与4个空白字符比较，即16×4=64次比较。虽然这样未用尽所有计算能力，但一个指令能代替64个比较以及「或」运算，还是很划算的。

我们可以使用 VC/gcc/clang 都支持的 instrinsic 函数去使用这个指令。这个指令的函数命名为 _mm_cmpistrm()，在nmmintrin.h中定义。

SkipWhitespace 的 SSE4.2 版本只能跳过字符串的输入流，其部分代码如下：

inline const char *SkipWhitespace_SIMD(const char* p) {
    // ... 非对齐处理

    static const char whitespace[16] = " \n\r\t";
    const __m128i w = _mm_load_si128((const __m128i *)&whitespace[0]);

    for (;; p += 16) {
        const __m128i s = _mm_load_si128((const __m128i *)p);
        const unsigned r = _mm_cvtsi128_si32(_mm_cmpistrm(w, s, 
            _SIDD_UBYTE_OPS | _SIDD_CMP_EQUAL_ANY |
            _SIDD_BIT_MASK | _SIDD_NEGATIVE_POLARITY));

        if (r != 0) {   // some of characters is non-whitespace
#ifdef _MSC_VER         // Find the index of first non-whitespace
            unsigned long offset;
            _BitScanForward(&offset, r);
            return p + offset;
#else
            return p + __builtin_ffs(r) - 1;
#endif
}

解析一下这里 _mm_cmpistrm() 用上了的选项：

_SIDD_UBYTE_OPS: 操作单位是无号字节，即16个 unsigned char。
_SIDD_CMP_EQUAL_ANY: 每次比较 s 里的字符，是否和 w 中的任意字符相等。
_SIDD_BIT_MASK: 以比特方式返回结果。
_SIDD_NEGATIVE_POLARITY: 把结果反转。这里指返回值的1代表非空白字符。

然后，我们用_mm_cvtsi128_si32()指令，把返回的最低位32字节储存成普通的32位整数。如果含有非空白字符，就使用_BitScanForward()或__builtin_ffs()计算出最早出现的非空白字符，并把指针跳到那里返回。

对齐问题

通过 SSE 读写内存，每次可以读写128位（16字节）数据。理想地是使用 128位对齐的地址来读写，这样会最大化读写速度。

最初我使用了 _mm_loadu_si128() 从非对齐的来源字符串读取16个字符。当时我觉得最多就是损失一些时间吧，问题似乎不大。但实际上还是出现了问题：

If rapidjson::SkipWhitespace_SIMD(char const*) is called at close to the end of string buffer which has less than 16 bytes of allocated space, the function will read beyond the memory it owns.

In our use case, we parse around 50 million JSON files/buffers per day and we got hit by the bug around 100 times per day on average before the workaround.

后来，我估计是因为用非对齐读取，有可能在边界会读到未分配的内存分页，做成很低机率的崩溃。因此，修正方法是先用普通代码处理未对齐的地址，然后才使用 SIMD 进行读取。

inline const char *SkipWhitespace_SIMD(const char* p) {
    // ...

    // 16-byte align to the next boundary
    const char* nextAligned = reinterpret_cast<const char*>(
        (reinterpret_cast<size_t>(p) + 15) & ~15);

    while (p != nextAligned)
        if (*p == ' ' || *p == '\n' || *p == '\r' || *p == '\t')
            ++p;
        else
            return p;

    // The rest of string using SIMD
    // ...
}

快速返回

优化其实还要看实际情况。我们发现，有比较多的情况是，第一个字符已是非空白字符。尤其是已去除空白字符的JSON，上面代码的初始时间还是比较大。因此，我们把第一个字符的检测独立出来。

inline const char *SkipWhitespace_SIMD(const char* p) {
    // Fast return for single non-whitespace
    if (*p == ' ' || *p == '\n' || *p == '\r' || *p == '\t')
        ++p;
    else
        return p;

    // ...
}

性能测试

测试环境

iMac 2.7 GHz Intel Core i5
Apple LLVM version 6.1.0 (clang-602.0.49) (based on LLVM 3.6.0svn)

测试用例 1

跳过1M个空白字符1000次。

基本实现: 675 ms
SSE4.2: 86 ms
strspn: 897 ms

测试用例 2

使用 SAX API 去原位解析（in situ parse）一个含缩进的 671KB sample.json，不处理事件（null handler）。

基本实现: 934 ms
SSE4.2: 650 ms

结语

RapidJSON 中使用 SSE4.2 指令集跳过空白字符，可以在一个迭代中进行 64 次字符比较，而且每次读取 128 位数据应该对内存频宽友好。为了兼容更旧的 x86 系 CPU，RapidJSON 也提供了一个 SSE2 的版本，但每个迭代需要执行更多指令，读取可参考源代码。

此优化只对含缩进的 JSON 有利，但我们通过「快速返回」使非缩进 JSON 也不会减慢，算是一种权衡之策。在后续的 v1.1 版本中，我希望尝试利用 SIMD 指令去快速扫瞄需处理转义（escaping）的字符，不需转义的部分能使用到 128 位复制至目标缓冲。由于转义符在 JSON 的出现率较低，此举应该能进一步提升整体性能。

最后，关于 x86/x64 系的 SIMD 指令，我推荐 Intel Instrinsic Guide 及 Agner Fog 的5本优化手册。

这两期都是比较低阶的东西，下期将会谈一些比较高层一点的，敬请关注。

RapidJSON 代码剖析（一）：混合任意类型的堆栈

Thu, 14 May 2015 00:00:00 +0000

大家好，这个专栏会分析 RapidJSON中一些有趣的 C++ 代码，希望对读者有所裨益。

C++ 语法解说

我们先来看一行代码（document.h）：

bool StartArray() {
    new (stack_.template Push<ValueType>()) ValueType(kArrayType); // <--
    return true;
}

或许你会问，这是什么C++语法？

这里其实用了两个可能较少接触的C++特性。第一个是 placement new，第二个是 template disambiguator。

Placement new

简单来说，placement new 就是不分配内存，由使用者给予内存空间来构建对象。其形式是：

new (T*) T(...);

第一个括号中的是给定的指针，它指向足够放下 T 类型的内存空间。而 T(...) 则是一个构造函数调用。那么，上面 StartArary() 里的代码，分开来写就是：

bool StartArray() {
    ValueType* v = stack_.template Push<ValueType>(); // (1)
    new (v) ValueType(kArrayType);                    // (2)
    return true;
}

这么分拆，(2)应该很容易理解吧。那么(1)是什么样的语法？为什么中间会有 template 这个关键字？

template disambiguator

(1)其实只是调用 Stack 类的模板成员函数 Push()。如果删去这个 template，代码就显得正常一点：

    ValueType* v = stack_.Push<ValueType>(); // (1)

这里 Push<ValueType>是一个 dependent name，它依赖于 ValueType 的实际类型。这里编译器不能确认 < 为小于运算符，还是模板的 <。为了避免歧义，需要加入template 关键字。这是C++标准的规定，缺少这个 template 关键字 gcc 和 clang 都会报错，而 vc 则会通过（C++标准也容许实现这样的编译器）。和这个语法相近的还有 typename disambiguator。

理解这些语法之后，我们进入核心问题。

混合任意类型的堆栈

处理树状的数据结构时，我们经常需要用到堆栈（stack）这种数据结构。C++ 标准库也提供了 std::stack 这个容器。然而，这个模板类容器的实例，只能存放一种类型的对象。在 RapidJSON 的解析过程中，我们希望它能同时存放已解析的 Value 对象，以及 Member 对象（key-value对）。或者我们从另一个角度去想，程序堆栈（program stack）本身就是可储存各种类型数据的堆栈。在 RapidJSON 中的其它地方也有这种需求。

在 internal/stack.h 中的 Stack 类实现了这个构思，其声明是这样的：

class Stack {
    Stack(Allocator* allocator, size_t stackCapacity);
    ~Stack();

    void Clear();
    void ShrinkToFit();
    
    template<typename T> T* Push(size_t count = 1);
    template<typename T> T* Pop(size_t count);
    template<typename T> T* Top();
    template<typename T> T* Bottom();

    Allocator& GetAllocator();
    bool Empty() const;
    size_t GetSize();
    size_t GetCapacity();
};

这个类比较特殊的地方，就是堆栈操作使用模板成员函数，可以压入或弹出不同类型的对象。另外，为了完全防止拷贝构造函数调用的可能性，这些函数都是返回指针。虽然引用也可以，但使用指针在一些应用情况下会更自然。

例如，要压入4个 int，再每次弹出两个：

Stack s;
*s.Push<int>() = 1;
*s.Push<int>() = 2;
*s.Push<int>() = 3;
*s.Push<int>() = 4;
for (int i = 0; i < 2; i++) {
    int* a = s.Pop<int>(2);
    std::cout << a[0] << " " << a[1] << std::endl;
}
// 输出：
// 3 4
// 1 2

注意到，Pop() 返回弹出的最底端元素的指针，我们仍然可以通过这指针合法地访问这些弹出的元素。

重要事项（坑出没注意）

在 StartArray() 的例子里，我们看到使用 placement new 来构建对象。在普通的情况下，new 和 delete 应该是成双成对的，但使用了 placement new，就通常不能使用 delete，因为 delete 会调用析构函数并释放内存。在这个例子里，stack_ 对象提供了内存空间，所以我们只需要调用 ValueType 的析构函数。例如，如果解析在中途终止了，我们要手动弹出已入栈的 ValueType 并调用其析构函数：

while (!stack_.Empty())
    (stack_.template Pop<ValueType>(1))->~ValueType();

另一个问题是，如果压入不同的数据类型，可能会有内存对齐问题，例如：

Stack s;
*s.Push<char>() = 'f';
*s.Push<char>() = 'o';
*s.Push<char>() = 'o';
*s.Push<int >() = 123; // 对齐问题

123写入的地址不是4的倍数，在一些CPU下可能造成崩溃。如果真的要做紧凑的packing，可以用 std::memcpy：

int i = 123;
std::memcpy(s.Push<int>(), &i, sizeof(i));

int j;
std::memcpy(&j, s.Pop<int>(1), sizeof(j));

代码复用

由于 RapidJSON 不依赖于 STL，在实现一些功能时缺少一些容器的帮忙。后来想到，一些地方其实可以把 Stack 当作可动态缩放的缓冲区来使用。例如，我们想从DOM生成JSON的字符串，就实现了 GenericStringBuffer：

template <typename Encoding, typename Allocator = CrtAllocator>
class GenericStringBuffer {
public:
    typedef typename Encoding::Ch Ch;
    
    // ...    

    void Put(Ch c) { *stack_.template Push<Ch>() = c; }

    const Ch* GetString() const {
        // Push and pop a null terminator. This is safe.
        *stack_.template Push<Ch>() = '\0';
        stack_.template Pop<Ch>(1);

        return stack_.template Bottom<Ch>();
    }

    size_t GetSize() const { return stack_.GetSize(); }

    // ...

    mutable internal::Stack<Allocator> stack_;
};

想在缓冲器末端加入字符，就使用 Stack::Push()，想把整个缓冲取出来，就简单地回传底端的指针。不过这里有个特别的地方，因为需要空字符作结尾，在 GetString() 时，会压入并立即弹出一个空字符。如前所述，弹出后、压入其他东西前，刚弹出的内容仍然是合法的。而由于我们希望GetString() 是 const 函数，所以这里让 stack_ 加上 mutable 修饰词。

结语

RapidJSON 为了一些内存及性能上的优化，萌生了一个混合任意类型的堆栈类 rapidjson::internal::Stack。但使用这个类要比 STL 提供的容器危险，必须清楚每个操作的具体情况、内存对齐等问题。而带来的好处是更自由的容器内容类型，可以达到高缓存一致性（用多个 std::stack 不利此因素），并且避免不必要内存分配、释放、对象拷贝构造等。从另一个角度看，这个类更像一种特殊的内存分配器。

实际软件工程中是否真的需要100%代码覆盖率（code coverage）？

Thu, 16 Apr 2015 00:00:00 +0000

以下是我的个人经历，可以作为一个案例参考。最后尝试总结。

我近年展开新软件项目时，都尽量以测试驱动的形式开发，常常有不少的单元测试。然而，之前尝试用 gcov/lcov 的结果有点问题，也没有加入连续整合（Continous Integration, CI）中，并不太关注覆盖率。或者更坦白地说，写程序二十多年来，也没怎么做覆盖率的分析。

我问这个问题之时，正在为 RapidJSON 的正式版做准备。刚刚上周末看到别的GitHub项目 nlohmann/json，它用上了一个叫 Coveralls 的免费服务，并声称该项目是 100% coverage。

好奇心驱使下，我也把这服务整合至RapidJSON中，经调整一些设定后，miloyip/rapidjson 跑出91% coverage。

「这也算是不错了吧？」我最初是这么想的。RapidJSON 本身有 5400 多行代码（LOC），而单元测试也另有 3500 多行。「这个测试代码量的比例已经不错了吧？」

然而，当我仔细分析没被覆盖的代码，并尝试把它们都覆盖，就发现一些情况：

找到了1个bug（Fixed a bug in trimming long number sequence），这是最严重的问题。原因是开发期间改变了一些参数，但忘了在一个条件下做出相应的改动。
找到了1个不应存在的公开API（Remove an invalid Document::ParseInsitu() API），这是在重构的时候加上的，当时忘了 insitu parsing 只允许来源编码和目的编码必须一致。
找到了一些未被执行、可以消去的代码（拟似死代码），主要出现于与浮点数转换相关的复杂算法里。这是由于那些代码都是参考别人的实现，逐渐变成现在的模样。例如原来strtod()的实现里，只有 FastPath 和 BigNumber 算法，后来在两者中间加入了 DiyFP 的算法，导致 BigNumber 中的一些分支条件不会再被触发。删去这些冗馀的代码可以优化性能，并减少代码量。但这些改动会存在风险，因为不知道是刚好单元测试没有覆盖到，还是真的冗馀。为了增强信心，唯有再审视代码的逻辑，并增加更多的测试数据及代码。
一些应该测试的分支，例如中途返回错误的地方。一些锁碎的编译器相关问题。例如 gcc 开了-Wswitch-default，但在default里做assert(false)这种没有覆盖的情况。

经过几天努力，60多个 commit、新增1000多行（不少新文件的license header⋯⋯）、删减200多行，终于完成了 100% line of code coverage 的 PR。

如其他答案所谈及，代码覆盖并不等于测试质量、代码质量。除非使用 Formal method，一般来说测试是无法证明代码的正确性的。但即使代码覆盖（甚至只是最简单的 line of code coverage）有许多潜在问题，适当地使用它作为一种手段／工具，也是有相当有帮助的，以下列出一些原因：

我是粗心大意、善忘的。在这个案例中，发现有许多问题是因为改动代码后，忘记了增加、修改相关测试。当项目开发持续很长时间，也会忘记许多约定、细节，修改代码时只求通过测试，而没考虑到修改会否令其他代码变成死代码。
我是懒惰的（较堂皇的说法是时间所限）。虽然理想地应该为每个函数去做单元测试，但有时候只测试了上一层的代码。并没有深究每个函数中是否完全覆盖。尤其通常只测试正常路径，而容易忽略一些异常路径。如果参考了别人的算法实现，更容易因为一知半解而忽略各种情况。

总括而言，我现在认为，最好是在 CI 中加入代码覆盖分析。如果能在开始开发时，以代码覆盖作为工具粗略分析测试是否充分，可以避免以上的一些问题。并且通过 CI，我们能追踪每个 commit 是否有潜在问题。尤其是分析开源项目中社区的PR时，能客观地看到是否缺乏最低限度的测试。

如果要简单地回答自己设下的问题，就是尽量达到100%的覆盖率。许多程序因为各种原因难以覆盖，或是所费精力太大，不必强求达至100%，但需要清楚了解个中原因。然后，除了关注覆盖率的绝对值，也要关注它的变化，求进步。

本文原发表于知乎，经过修改。

SIGGRAPH Asia 2014 见闻之《高效地使用大量光源于实时着色》课程

Mon, 15 Dec 2014 00:00:00 +0000

在 SIGGRAPH Asia 2014 中，《高效地使用大量光源于实时着色（Efficient Real-TimeShading with Many Lights）》是和游戏技术最接近的课程之一。三位主讲分别是 Ola Olsson（瑞典查尔姆斯理工大学博士）、Emil Persson（Avalanche Studios研究部负责人）、Markus Billeter（瑞典查尔姆斯理工大学博士候选人）。课程内容比较前向、延迟、分块、群组和相关技术实现大量动态光源的渲染管道。由于现时未获演讲稿的电子版本，笔者尽量以记忆及相关文献简单介绍一下本课程的重点。

近年，实时渲染管道经历了一连串变革，全动态光源对这些变革有重要影响。传统的前向渲染（forward rendering）管道在渲染$n$个物体在$m$个光源下着色，需要绘制$\mathrm{O}(nm)$次。当需要越来越复杂的游戏场景，更多光源，这种方式成为CPU及GPU的性能瓶颈。在2004年 GDC 出现了延迟渲染（deferred rendering）管道的讨论[4]，所有物体都先绘制在一组屏幕空间的缓冲（称为几何缓冲区／G-buffer，见图1），再逐光源对该缓冲着色，复杂度变成$\mathrm{O}(n + m)$。另一种相关的技术在同一届 GDC 中发表，被称为延迟光照（deferred lighing）[3]，几年后也被称为前期光照通道（light pre-pass）[2]。通过这类“延迟”方式，已可以大量增加物体和光源的数量，渲染出更复杂的场景。然而，这种延迟方式有几个问题。首先，只能使用统一的材质着色器，而且其参数受限（每个参数需要相应的G-buffer），这对于游戏的画面风格造成很大的限制。第二，在性能上虽然复杂度降低了，但读写G-buffer的内存带宽用量成为了性能瓶颈。由于GPU的计算性能不断提升但显存带宽却提升缓慢，使延迟渲染越来越不适合近代的GPU。第三，不能处理半透明及多重采样抗锯齿（MultiSampling Anti-Aliasing, MSAA）。


(a) 漫反射缓冲区	(b) 深度缓冲区	(c) 法线缓冲区	(d) 最终结果

图1：延迟渲染的几何缓冲区／G-buffer及渲染结果（维基百科图片）

因为这些因素，近几年催生出另一族渲染管道的方式，称为分块渲染（tiled rendering）[5]。分块渲染有多个变种，先说分块延迟渲染（tiled deferred rendering）。在前面提及，延迟渲染的瓶颈在于读写 G-buffer，在大量光源下，具体瓶颈将位于每个光源对 G-buffer的读取及与颜色缓冲区（color buffer）混合。这里的问题是，每个光源，即使它们的影响范围在屏幕空间上有重疉，因为每个光源是在不同的绘制中进行，所以会重复读取G-buffer中相同位置的数据，计算后以相加混合方式写入颜色缓冲。光源越多，内存带宽用量越大。而分块延迟渲染则是把屏幕分拆成细小的栅格，例如每 32 × 32 象素作为一个分块（tile）。然后，计算每个分块会受到哪些光源影响，把那些光源的索引储存在分块的光源列表里。最后，逐个分块进行着色，对每像素读取 G-buffer 和光源列表及相关的光源信息。因此，G-buffer的数据只会被读取1次且仅1次，写入 color buffer 也是1次且仅1次，大幅降低内存带宽用量。不过，这种方法需要计算光源会影响哪些分块，这个计算又称为光源剔除（light culling），可以在 CPU 或 GPU（通常以 compute shader 实现）中进行。用GPU计算的好处是，GPU 计算这类工作比 CPU 更快，也减少 CPU／GPU 数据传输。而且，可以计算每个分块的深度范围（depth range），作更有效的剔除。


(a) 渲染结果	(b) 光源分块

图2：分块渲染（图片来自 Olaolss 的网页）

有趣的是，这种分块方式也可以用于前向渲染，这称为分块前向渲染（tiled forward rendering）[1]。当计算好光源列表，前向渲染时就按屏幕位置读取相关的光源信息去着色。那么，就可以同时解决延迟渲染的各种问题，又不需要像传统前向渲染对物体进行多次绘制。这种分块渲染似乎已经很理想，但如果增加更多光源，而场景又比较空扩，每个分块的光源数量就会变得更多。虽然做了深度范围的优化可缓解这个问题，但如果在视野里有很多深度不连续区域（depth discontinuities），如图3，那么该优化也无能为力了。为了解决这个问题，研究者想出了不同的新方法。


(a) 渲染结果	(b) 深度不连续的区域

图3：深度不连续的场景（图片来自[8]）

Olsson、Billeter 及他们的导师 Ulf Assarsson 在2012年发表了一种新的改善方式，名为分群组渲染（clustered rendering）[6][7]。这里的群组（cluster）是指分块（tile）在深度上进一步划分，这种体积数据使每个单位储存更少量的光源（图4）。在渲染时，除了考虑着色像素的屏幕坐标，还考虑到深度的坐标，去索引群组并取得光源信息。这个简单的概念优化了光源剔除，使光源数目能进一步提升。


(a) 屏幕空间上仍是栅格式划分	(b) 但从侧面可看到深度被划分成多个群组

图4：群组渲染（图片来自Olaolss的网页 3）

据游戏业界的Persson称，以他所知，暂时未有已发行游戏使用了群组渲染技术。而他在Avalanche Studios开发中的《正当防卫3（Just Cause 3）》则使用了此技术[8]。对于实际在游戏中应用群组渲染技术，他表示非常乐观。在开发本作中，他从实际的场景中发现，如果简单地使用指数方式划分深度，较近的范围可能有太多群组，而使效率变差。所以他把最近的群组加深，有效改善此问题。另外，由于该作主要是室外大型场景，远景就不使用真正的动态光照，而仅使用公告板作渲染。


(a) 缺省的指数深度分布	(b) 特殊的近景深度分布

图5：Avalanche 工作室对群组深度分布的优化（图片来自[8]）

不过，在光照上还有一个未有完善解决的问题，就是阴影。笔者记得，以前在解决虚拟点光源模拟全局光照的阴影问题时，曾出现一种名为不完美阴影贴图（imperfect shadow map, ISM）的技术[9]。刚好在这课程的前一天 Square Enix 的德吉雄介也谈到使用ISM于他们的全局渲染管道中[10]。然而，本课程中 Olsson 就介绍了他和 Billeter 及其他同事合作发明的一个方案，称为虚拟阴影贴图（virtual shadow map），采用类似 id Tech 5 的虚拟纹理（virtual texturing）技术，去动态按阴影采样需求动态分配阴影贴图的纹理空间。其结果也是不错的，虽然使用了较大量的显存，但似乎在这一代游戏机平台上是有可能应用到的。

最后 Billeter 讲述在移动平台上实现多光源的尝试，由于移动设备的内存带宽比PC的问题更大，使用分块或群组渲染都更有竞争力。可望在近一两年内在高端手机游戏中实际应用。

参考文献

[1] Markus Billeter, Ola Olsson, and Ulf Assarsson. Tiled forward shading. GPU Pro 4: Advanced Rendering Techniques, 4:99, 2013.

[2] Wolfgang Engel. Designing a renderer for multiple lights–the light pre-pass renderer. ShaderX7: Advanced rendering techniques, 2009.

[3] Rich Geldreich, Matt Pritchard, and John Brooks. Deferred lighting and shading. In Game Developers Conference, volume2, 2004.

[4] Shawn Hargreaves and Mark Harris. Deferred shading. In Game Developers Conference, volume 2, 2004.

[5] Ola Olsson and Ulf Assarsson. Tiled shading. Journal of Graphics, GPU, and Game Tools, 15(4):235–251, 2011.

[6] Ola Olsson, Markus Billeter, and Ulf Assarsson. Clustered deferred and forward shading. In HPG ’12: Proceedings of the Conference on High Performance Graphics 2012, 2012.

[7] Ola Olsson, Markus Billeter, and Ulf Assarsson. Tiled and clustered forward shading. In SIGGRAPH ’12: ACM SIGGRAPH 2012 Talks, New York, NY, US- A, 2012. ACM.

[8] Emil Persson and Ola Olsson. Practical clustered deferred and forward shading. SIGGRAPH Course: Advances in Real-Time Rendering in Games, 2013.

[9] Tobias Ritschel, Thorsten Grosch, Min H Kim, H-P Seidel, Carsten Dachsbacher, and Jan Kautz. Imperfect shadow maps for efficient computation of indirect illumination. In ACM Transactions on Graphics (TOG), volume 27, page 129. ACM, 2008.

[10] Yusuke Tokuyoshi. Virtual spherical gaussian lights for real-time glossy indirect illumination. In SIGGRAPH Asia 2014 Technical Briefs, page 17. ACM, 2014.

本文原于2014年12月15日在腾讯内部揭载，获授权公开。

如何用 C 语言画一棵圣诞树

Fri, 12 Dec 2014 00:00:00 +0000

Sierpinski 三角形

首先，我尝试用左右镜像的 Sierpinski 三角形，每层减去上方一小块，再用符号点缀。可生成不同层数的「圣诞树」，如下图是5层的结果。

#include <stdio.h>
#include <stdlib.h>

int main(int argc, char* argv[]) {
    int n = argc > 1 ? atoi(argv[1]) : 4;
    for (int j = 1; j <= n; j++) {
        int s = 1 << j, k = (1 << n) - s, x;
        for (int y = s - j; y >= 0; y--, putchar('\n')) {
            for (x = 0; x < y + k; x++) printf("  ");
            for (x = 0; x + y < s; x++) printf("%c ", '!' ^ y & x);
            for (x = 1; x + y < s; x++) printf("%c ", '!' ^ y & (s - y - x - 1));
        }
    }
}

基本代码来自 rosettacode，字符的想法来自于 code golf - Draw A Sierpinski Triangle。

递归

上面的是我尝试尽量用最少代码来画一个抽象一点的圣诞树，因此树干都没有。然后，我尝试用更真实一点的风格。因为树是一个比较自相似的形状，这次使用递归方式描述树干和分支。

$n = 0$ 的时候，就是只画一主树干，树干越高就越幼：

$n = 1$ 的时候，利用递归画向两面分支，旋转，越高的部分缩得越小。

$n = 2$ 的时候，继续分支出更细的树支。

$n = 3$ 就差不多够细节了。

代码长一点，为了容易理解我不「压缩」它了。

#include <math.h>
#include <stdio.h>
#include <stdlib.h>

#define PI 3.14159265359

float sx, sy;

float sdCircle(float px, float py, float r) {
    float dx = px - sx, dy = py - sy;
    return sqrtf(dx * dx + dy * dy) - r;
}

float opUnion(float d1, float d2) {
    return d1 < d2 ? d1 : d2;
}

#define T px + scale * r * cosf(theta), py + scale * r * sin(theta)

float f(float px, float py, float theta, float scale, int n) {
    float d = 0.0f;
    for (float r = 0.0f; r < 0.8f; r += 0.02f)
        d = opUnion(d, sdCircle(T, 0.05f * scale * (0.95f - r)));

    if (n > 0)
        for (int t = -1; t <= 1; t += 2) {
            float tt = theta + t * 1.8f;
            float ss = scale * 0.9f;
            for (float r = 0.2f; r < 0.8f; r += 0.1f) {
                d = opUnion(d, f(T, tt, ss * 0.5f, n - 1));
                ss *= 0.8f;
            }
        }

    return d;
}

int main(int argc, char* argv[]) {
    int n = argc > 1 ? atoi(argv[1]) : 3;
    for (sy = 0.8f; sy > 0.0f; sy -= 0.02f, putchar('\n'))
        for (sx = -0.35f; sx < 0.35f; sx += 0.01f)
            putchar(f(0, 0, PI * 0.5f, 1.0f, n) < 0 ? '*' : ' ');
}

这段代码实际上是用了圆形的距离场来建模，并且没有优化。

这是一棵「祼树」，未能称得上是「圣诞树」。

加入装饰

简单地加入装饰及丝带，在命令行可以选择放大倍率，下图是两倍大的。

// f() 及之前的部分沿上

int ribbon() {
    float x = (fmodf(sy, 0.1f) / 0.1f - 0.5f) * 0.5f;
    return sx >= x - 0.05f && sx <= x + 0.05f;
}

int main(int argc, char* argv[]) {
    int n = argc > 1 ? atoi(argv[1]) : 3;
    float zoom = argc > 2 ? atof(argv[2]) : 1.0f;
    for (sy = 0.8f; sy > 0.0f; sy -= 0.02f / zoom, putchar('\n'))
        for (sx = -0.35f; sx < 0.35f; sx += 0.01f / zoom) {
            if (f(0, 0, PI * 0.5f, 1.0f, n) < 0.0f) {
                if (sy < 0.1f)
                    putchar('.');
                else {
                    if (ribbon())
                        putchar('=');
                    else
                        putchar("............................#j&o"[rand() % 32]);
                }
            }
            else
                putchar(' ');
        }
}

2D 的我想已差不多了。接下来看看有没有空尝试 3D 的。

3D

终于要3D了。之前每个节点是往左和右分支，在三维中我们可以更自由一点，我尝试在每个节点申出6个分支。最后用了简单的 Lambertian 着色（即$\max(\mathbf{N} \cdot \mathbf{L}, 0)$）。

$n = 1$ 的时候比较容易看出立体的着色：

可是$n=3$的时候已乱得难以辨认：

估计是因为 aliasing 而做成的。由于光照已经使用了 finite difference 来计算法线，性能已经很差，我就不再尝试做 supersampling 去解决 aliasing 的问题了。另外也许 ambient occlusion 对这问题也有帮助，不过需要更多的采样。

因为需要三维旋转，不能像二维简单使用一个角度来代表旋转，所以这段代码加入了不少矩阵运算。当然用四元数也是可以的。

#include <math.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define PI 3.14159265359f

float sx, sy;

typedef float Mat[4][4];
typedef float Vec[4];

void scale(Mat* m, float s) {
    Mat temp = { {s,0,0,0}, {0,s,0,0 }, { 0,0,s,0 }, { 0,0,0,1 } };
    memcpy(m, &temp, sizeof(Mat));
}

void rotateY(Mat* m, float t) {
    float c = cosf(t), s = sinf(t);
    Mat temp = { {c,0,s,0}, {0,1,0,0}, {-s,0,c,0}, {0,0,0,1} };
    memcpy(m, &temp, sizeof(Mat));
}

void rotateZ(Mat* m, float t) {
    float c = cosf(t), s = sinf(t);
    Mat temp = { {c,-s,0,0}, {s,c,0,0}, {0,0,1,0}, {0,0,0,1} };
    memcpy(m, &temp, sizeof(Mat));
}

void translate(Mat* m, float x, float y, float z) {
    Mat temp = { {1,0,0,x}, {0,1,0,y}, {0,0,1,z}, {0,0,0,1} };
    memcpy(m, &temp, sizeof(Mat));
}

void mul(Mat* m, Mat a, Mat b) {
    Mat temp;
    for (int j = 0; j < 4; j++)
        for (int i = 0; i < 4; i++) {
            temp[j][i] = 0.0f;
            for (int k = 0; k < 4; k++)
                temp[j][i] += a[j][k] * b[k][i];
        }
    memcpy(m, &temp, sizeof(Mat));    
}

void transformPosition(Vec* r, Mat m, Vec v) {
    Vec temp = { 0, 0, 0, 0 };
    for (int j = 0; j < 4; j++)
        for (int i = 0; i < 4; i++)
            temp[j] += m[j][i] * v[i];
    memcpy(r, &temp, sizeof(Vec));    
}

float transformLength(Mat m, float r) {
    return sqrtf(m[0][0] * m[0][0] + m[0][1] * m[0][1] + m[0][2] * m[0][2]) * r;
}

float sphere(Vec c, float r) {
    float dx = c[0] - sx, dy = c[1] - sy;
    float a = dx * dx + dy * dy;
    return a < r * r ? sqrtf(r * r - a) + c[2] : -1.0f;
}

float opUnion(float z1, float z2) {
    return z1 > z2 ? z1 : z2;
}

float f(Mat m, int n) {
    float z = -1.0f;
    for (float r = 0.0f; r < 0.8f; r += 0.02f) {
        Vec v = { 0.0f, r, 0.0f, 1.0f };
        transformPosition(&v, m, v);
        z = opUnion(z, sphere(v, transformLength(m, 0.05f * (0.95f - r))));
    }

    if (n > 0) {
        Mat ry, rz, s, t, m2, m3;
        rotateZ(&rz, 1.8f);

        for (int p = 0; p < 6; p++) {
            rotateY(&ry, p * (2 * PI / 6));
            mul(&m2, ry, rz);
            float ss = 0.45f;
            for (float r = 0.2f; r < 0.8f; r += 0.1f) {
                scale(&s, ss);
                translate(&t, 0.0f, r, 0.0f);
                mul(&m3, s, m2);
                mul(&m3, t, m3);
                mul(&m3, m, m3);
                z = opUnion(z, f(m3, n - 1));
                ss *= 0.8f;
            }
        }
    }

    return z;
}

float f0(float x, float y, int n) {
    sx = x;
    sy = y;
    Mat m;
    scale(&m, 1.0f);
    return f(m, n);
}

int main(int argc, char* argv[]) {
    int n = argc > 1 ? atoi(argv[1]) : 3;
    float zoom = argc > 2 ? atof(argv[2]) : 1.0f;
    for (float y = 0.8f; y > -0.0f; y -= 0.02f / zoom, putchar('\n'))
        for (float x = -0.35f; x < 0.35f; x += 0.01f / zoom) {
            float z = f0(x, y, n);
            if (z > -1.0f) {
                float nz = 0.001f;
                float nx = f0(x + nz, y, n) - z;
                float ny = f0(x, y + nz, n) - z;
                float nd = sqrtf(nx * nx + ny * ny + nz * nz);
                float d = (nx - ny + nz) / sqrtf(3) / nd;
                d = d > 0.0f ? d : 0.0f;
                // d = d < 1.0f ? d : 1.0f;
                putchar(".-:=+*#%@@"[(int)(d * 9.0f)]);
            }
            else
                putchar(' ');
        }
}

性能优化

考虑提升性能时，一般是需要一些空间剖分的方式去加速检查，但这里刚好是一个树状的场景结构，可以简单使用 bounding volume hierarchy，我使用了球体作为包围体积。只需加几句代码，便可以大大缩减运行时间。

另外，考虑到太小的叶片是很难采样得到好看的结果，我尝试以一个较大的球体去表现叶片（就如素描时考虑更整体的光暗而不是每片叶片的光暗），我觉得结果有进步。

float f(Mat m, int n) {
    // Culling
    {
        Vec v = { 0.0f, 0.5f, 0.0f, 1.0f };
        transformPosition(&v, m, v);        
        if (sphere(v, transformLength(m, 0.55f)) == -1.0f)
            return -1.0f;
    }

    float z = -1.0f;

    if (n == 0) { // Leaf
        Vec v = { 0.0f, 0.5f, 0.0f, 1.0f };
        transformPosition(&v, m, v);        
        z = sphere(v, transformLength(m, 0.3f));
    }  
    else { // Branch
        for (float r = 0.0f; r < 0.8f; r += 0.02f) {
            Vec v = { 0.0f, r, 0.0f, 1.0f };
            transformPosition(&v, m, v);
            z = opUnion(z, sphere(v, transformLength(m, 0.05f * (0.95f - r))));
        }
    }

    // ...
}

结语

其实我在回答这问题的时候，并没有计划，只是一步一步地尝试。现在我觉得用这规模的代码大概不能再怎么进展了。不过今天看到大堂里的圣诞树，觉得那些装饰物还挻有趣的，有时候除了画整体，也可以画局部，看看是否能再更新。

本文原发表于知乎，经过修改。

如何用 C 语言画一个心形

Wed, 10 Dec 2014 00:00:00 +0000

基础版

这版本使用了一个函数 heart curve：

$f(x, y) = (x^2 + y^2 - 1)^3 - x^2y^3$

#include <stdio.h>

int main() {
    for (float y = 1.5f; y > -1.5f; y -= 0.1f) {
        for (float x = -1.5f; x < 1.5f; x += 0.05f) {
            float a = x * x + y * y - 1;
            putchar(a * a * a - x * x * y * y * y <= 0.0f ? '*' : ' ');
        }
        putchar('\n');
    }
}

花纹版

这其实是该函数的 level set。

#include <stdio.h>

int main() {
    for (float y = 1.5f; y > -1.5f; y -= 0.1f) {
        for (float x = -1.5f; x < 1.5f; x += 0.05f) {
            float z = x * x + y * y - 1;
            float f = z * z * z - x * x * y * y * y;
            putchar(f <= 0.0f ? ".:-=+*#%@"[(int)(f * -8.0f)] : ' ');
        }
        putchar('\n');
    }
}

3D版

Heart surface 是一个隐含函数的等值面：

$\left (x^2 + \frac{9}{4} y^2 z^2 - 1 \right)^3 - x^2 z^3 - \frac{9}{80} y^2 z^3 = 0$

这个实现简单使用迭代法求出每个$(x, y)$的$z$，然后用finite difference求法矢量，用wrapped diffuse着色。

#include <stdio.h>
#include <math.h>

float f(float x, float y, float z) {
    float a = x * x + 9.0f / 4.0f * y * y + z * z - 1;
    return a * a * a - x * x * z * z * z - 9.0f / 80.0f * y * y * z * z * z;
}

float h(float x, float z) {
    for (float y = 1.0f; y >= 0.0f; y -= 0.001f)
        if (f(x, y, z) <= 0.0f)
            return y;
    return 0.0f;
}

int main() {
    for (float z = 1.5f; z > -1.5f; z -= 0.05f) {
        for (float x = -1.5f; x < 1.5f; x += 0.025f) {
            float v = f(x, 0.0f, z);
            if (v <= 0.0f) {
                float y0 = h(x, z);
                float ny = 0.01f;
                float nx = h(x + ny, z) - y0;
                float nz = h(x, z + ny) - y0;
                float nd = 1.0f / sqrtf(nx * nx + ny * ny + nz * nz);
                float d = (nx + ny - nz) * nd * 0.5f + 0.5f;
                putchar(".:-=+*#%@"[(int)(d * 5.0f)]);
            }
            else
                putchar(' ');
        }
        putchar('\n');
    }
}

彩色版

把「3D版」输出至 PPM 文件，可以用 Photoshop 打开。另外降低了ny的值导致有超有趣的 pattern，就保留下来吧。

#ifdef _MSC_VER
#define _CRT_SECURE_NO_WARNINGS
#endif
#include <stdio.h>
#include <math.h>

float f(float x, float y, float z) {
    float a = x * x + 9.0f / 4.0f * y * y + z * z - 1;
    return a * a * a - x * x * z * z * z - 9.0f / 80.0f * y * y * z * z * z;
}

float h(float x, float z) {
    for (float y = 1.0f; y >= 0.0f; y -= 0.001f)
        if (f(x, y, z) <= 0.0f)
            return y;
    return 0.0f;
}

int main() {
    FILE* fp = fopen("heart.ppm", "w");
    int sw = 512, sh = 512;
    fprintf(fp, "P3\n%d %d\n255\n", sw, sh);
    for (int sy = 0; sy < sh; sy++) {
        float z = 1.5f - sy * 3.0f / sh;
        for (int sx = 0; sx < sw; sx++) {
            float x = sx * 3.0f / sw - 1.5f;
            float v = f(x, 0.0f, z);
            int r = 0;
            if (v <= 0.0f) {
                float y0 = h(x, z);
                float ny = 0.001f;
                float nx = h(x + ny, z) - y0;
                float nz = h(x, z + ny) - y0;
                float nd = 1.0f / sqrtf(nx * nx + ny * ny + nz * nz);
                float d = (nx + ny - nz) / sqrtf(3) * nd * 0.5f + 0.5f;
                r = (int)(d * 255.0f);
            }
            fprintf(fp, "%d 0 0 ", r);
        }
        fputc('\n', fp);
    }
    fclose(fp);
}

ASCII动画

通过空间的缩放变换实现 ASCII 心跳动画，需要改变光标位置，此版本仅支持 Windows。录制视频不太顺畅，建议在本地测试。

#include <stdio.h>
#include <math.h>
#include <windows.h>
#include <tchar.h>

float f(float x, float y, float z) {
    float a = x * x + 9.0f / 4.0f * y * y + z * z - 1;
    return a * a * a - x * x * z * z * z - 9.0f / 80.0f * y * y * z * z * z;
}

float h(float x, float z) {
    for (float y = 1.0f; y >= 0.0f; y -= 0.001f)
        if (f(x, y, z) <= 0.0f)
            return y;
    return 0.0f;
}

int main() {
    HANDLE o = GetStdHandle(STD_OUTPUT_HANDLE);
    _TCHAR buffer[25][80] = { _T(' ') };
    _TCHAR ramp[] = _T(".:-=+*#%@");

    for (float t = 0.0f;; t += 0.1f) {
        int sy = 0;
        float s = sinf(t);
        float a = s * s * s * s * 0.2f;
        for (float z = 1.3f; z > -1.2f; z -= 0.1f) {
            _TCHAR* p = &buffer[sy++][0];
            float tz = z * (1.2f - a);
            for (float x = -1.5f; x < 1.5f; x += 0.05f) {
                float tx = x * (1.2f + a);
                float v = f(tx, 0.0f, tz);
                if (v <= 0.0f) {
                    float y0 = h(tx, tz);
                    float ny = 0.01f;
                    float nx = h(tx + ny, tz) - y0;
                    float nz = h(tx, tz + ny) - y0;
                    float nd = 1.0f / sqrtf(nx * nx + ny * ny + nz * nz);
                    float d = (nx + ny - nz) * nd * 0.5f + 0.5f;
                    *p++ = ramp[(int)(d * 5.0f)];
                }
                else
                    *p++ = ' ';
            }
        }

        for (sy = 0; sy < 25; sy++) {
            COORD coord = { 0, sy };
            SetConsoleCursorPosition(o, coord);
            WriteConsole(o, buffer[sy], 79, NULL, 0);
        }
        Sleep(33);
    }
}

Shadertoy

移植至 Shadertoy，加入高光和背景。

本文原发表于知乎，经过修改。