RenderTexture的作用是捕捉画面并输出到Texture或者文件。其底层实现是OpenGL自建帧缓冲（FrameBuffer）。

一、帧缓冲知识

语雀内容
帧缓冲包含以下部分：

颜色缓冲（Color Buffer）
- 存放最终渲染数据，视口（ViewPort）显示的画面就来自于此。
深度缓冲（Depth Buffer）
- 保存每个像素的深度值
模板缓冲（Stencil Buffer）
- 保存每个像素的模板值

OpenGL渲染管线生成的像素默认是输出到默认帧缓冲中（default framebuffer），ViewPort视口显示的画面（像素数据）一直是从默认帧缓冲中获取。当我们绑定一个自建的帧缓冲到GL_FRAMEBUFFER时，渲染数据将输出到自建帧缓冲的颜色缓冲中，然后我们就可以从中提取渲染数据，注意此时当前绑定的帧缓冲并不是默认帧缓冲，因此渲染数据并不会显示到视口上。

二、使用示例


auto winSize        = Director::getInstance()->getWinSize();
auto renderTexture = RenderTexture::create(winSize.width, 
                                           winSize.height, 
                                           Texture2D::PixelFormat::RGBA8888);
auto sp            = Sprite::create(......);
addChild(renderTexture);
renderTexture.begin();
sp.visit();                // 将 begin、end之间的绘制输出到自建帧缓冲
renderTexture.end();
// 清空颜色缓冲，相当于调用：glClearColor and glClear(GL_COLOR_BUFFER_BIT);
renderTexture->clear(float r, float g, float b, float a);    
// 将颜色缓冲区数据输出到图片文件
bool sucess = renderTexture->saveToFile(filename,                            // 文件名
                                           Image::Format::PNG,                    // 保存的图片文件格式
                                           [](RenderTexture* rt,                // renderTexture
                                             const std::string& filePath) {    // 保存到文件路径
                           });
// Add this function to avoid crash if we switch to a new scene.
Director::getInstance()->getRenderer()->render();
if(sucess){
    // 保存成功。
}
// 获取输出的纹理数据，可用于再创建
auto sprite = Sprite::createWithTexture( renderTexture->getSprite()->getTexture() );

三、源码分析

1、initWithWidthAndHeight

初始化函数。主要的工作是构建自定义帧缓冲，包括：

颜色附件：纹理类型，由一个Texture2D*指向
深度附件
模板附件 ```cpp

bool RenderTexture::initWithWidthAndHeight( int w, int h, // renderTexture的宽高 Texture2D::PixelFormat format, // 帧缓冲颜色附件格式，也即是纹理格式，只支持RGB、RGBA GLuint depthStencilFormat) // 帧缓冲深度/模板附件 { CCASSERT(format != Texture2D::PixelFormat::A8, “only RGB and RGBA formats are valid for a render texture”);

bool ret = false;
void *data = nullptr;
do 
{
    _fullRect = _rtTextureRect = Rect(0,0,w,h);
    //Size size = Director::getInstance()->getWinSizeInPixels();
    //_fullviewPort = Rect(0,0,size.width,size.height);
    w = (int)(w * CC_CONTENT_SCALE_FACTOR());
    h = (int)(h * CC_CONTENT_SCALE_FACTOR());
    _fullviewPort = Rect(0,0,w,h);
    glGetIntegerv(GL_FRAMEBUFFER_BINDING, &_oldFBO);    // 保存在当前已绑定的帧缓冲，方便后续恢复
                                                        // 默认帧缓冲 = 0
    // *****************************************************
    // 下面的工作主要构件一个合适大小的纹理，作为帧缓冲的颜色附件（纹理类型）
    // *****************************************************
    // textures must be power of two squared
    int powW = 0;
    int powH = 0;
    if (Configuration::getInstance()->supportsNPOT())
    {
        powW = w;
        powH = h;
    }
    else
    {
        powW = ccNextPOT(w);
        powH = ccNextPOT(h);
    }
    auto dataLen = powW * powH * 4;        // 最大的纹理格式就是RGBA888，4个byte
    data = malloc(dataLen);
    CC_BREAK_IF(! data);
    memset(data, 0, dataLen);            // 内存区域初始化为0
    _pixelFormat = format;
    if (_texture = new (std::nothrow) Texture2D())
    {
        // 通过内存中的图像数据（imagedata）data，在显存中创建一个纹理
        _texture->initWithData(data,  dataLen, 
                               (Texture2D::PixelFormat)_pixelFormat, // 纹理格式
                               powW, powH,                              // 纹理的像素狂傲
                               Size((float)w, (float)h));
    }
    ......
    GLint oldRBO;
    glGetIntegerv(GL_RENDERBUFFER_BINDING, &oldRBO);    // 保存当前已绑定的渲染缓冲，相关知识见：https://www.yuque.com/tvvhealth/cs/kos5bz
    // _textureCopy主要是用于解决某些高通GPU的会出现的问题
    /*  Certain Qualcomm Adreno GPU's will retain data in memory after a frame buffer 
    switch which corrupts the render to the texture. 
    The solution is to clear the frame buffer before rendering to the texture. However,
    calling glClear has the unintended result of clearing the current texture. 
    Create a temporary texture to overcome this. 
    At the end of RenderTexture::begin(),
    switch the attached texture to the second one, call glClear, and then switch back to 
    the original texture. This solution is unnecessary for other devices as they don't have
    the same issue with switching frame buffers.
     */
    if (Configuration::getInstance()->checkForGLExtension("GL_QCOM"))
    {
        _textureCopy = new (std::nothrow) Texture2D();
        if (_textureCopy)
        {
            _textureCopy->initWithData(data, dataLen, 
                                       (Texture2D::PixelFormat)_pixelFormat, 
                                       powW, powH, 
                                       Size((float)w, (float)h));
        }
        else
        {
            break;
        }
    }
    glGenFramebuffers(1, &_FBO);                // 创建帧缓冲
    glBindFramebuffer(GL_FRAMEBUFFER, _FBO);    // 绑定到当前帧缓冲
    // associate texture with FBO
    // 将帧缓冲的颜色附件设置为_texture纹理，也即是设置为纹理类型附件。
    glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, _texture->getName(), 0);
    // 帧缓冲还必须构建深度、模板附件，否则framebuffer is not complete
    if (depthStencilFormat != 0) {
        _depthAndStencilFormat = depthStencilFormat;
        setupDepthAndStencil(powW, powH);    // 见下面解释
    }
    // 检查帧缓冲的完整性，非常有必要
    CCASSERT(glCheckFramebufferStatus(GL_FRAMEBUFFER) == GL_FRAMEBUFFER_COMPLETE, "Could not attach texture to framebuffer");
    // 设置抗锯齿效果，其实做的就是设置的纹理的Filtering为Linear
    // 这更消耗性能，不知道为什么一定要这么干。
    _texture->setAntiAliasTexParameters();
    if (_textureCopy) {
        _textureCopy->setAntiAliasTexParameters();
    }
    // 这里主要是让RenderTexture能显示出来，自建的帧缓冲的颜色附件是不会被输出到屏幕上的
    setSprite(Sprite::createWithTexture(_texture));
    _texture->release();
    _sprite->setFlippedY(true);
    // alpha预乘：GL_ONE, GL_ONE_MINUS_SRC_ALPHA
    _sprite->setBlendFunc( BlendFunc::ALPHA_PREMULTIPLIED );
    _sprite->setOpacityModifyRGB(true);
    // 切换会默认帧缓冲，_FBO保存了我们创建的帧缓冲
    glBindRenderbuffer(GL_RENDERBUFFER, oldRBO);
    glBindFramebuffer(GL_FRAMEBUFFER, _oldFBO);
    // Disabled by default.
    _autoDraw = false;
    // add sprite for backward compatibility
    addChild(_sprite);
    ret = true;
} while (0);
CC_SAFE_FREE(data);
return ret;

}

```cpp
// 构建帧缓冲的深度、模板附件
void RenderTexture::setupDepthAndStencil(int powW, int powH)
{
    ......;    // 这里是android平台的构建逻辑，我们只看windows平台的，原理都一样
    // 附件类型是渲染缓冲类型RenderBuffer，这种类型的好处在于写入速度非常快，但前提是不会被读取
    // 深度、模板值，应用端很少需要去读取，所以非常适合。
    glGenRenderbuffers(1, &_depthRenderBuffer);                    // 创建渲染缓冲对象
    glBindRenderbuffer(GL_RENDERBUFFER, _depthRenderBuffer);    // 绑定到当前渲染缓冲类型
    glRenderbufferStorage(GL_RENDERBUFFER,                        // 给当前绑定的renderbuffer分配数据存储内存并指定格式
                          _depthAndStencilFormat,                // 格式
                          (GLsizei)powW, (GLsizei)powH);        // 大小
    // 将当前的帧缓冲对象的深度附件设置为将当前绑定的渲染缓冲对象（即_depthRenderBuffer）
    glFramebufferRenderbuffer(GL_FRAMEBUFFER, 
                              GL_DEPTH_ATTACHMENT,
                              GL_RENDERBUFFER,
                              _depthRenderBuffer);
    // if depth format is the one with stencil part, 
    // bind same render buffer as stencil attachment
    // GL_DEPTH24_STENCIL8表示帧缓冲_depthRenderBuffer管理的数据存储区的每个像素的前24bit为深度值，然后是8bit的模板值
    // 所以我们还要设置帧缓冲的模板附件同样为当前绑定的渲染缓冲对象（即_depthRenderBuffer）
    if (_depthAndStencilFormat == GL_DEPTH24_STENCIL8) {
        glFramebufferRenderbuffer(GL_FRAMEBUFFER,
                                  GL_STENCIL_ATTACHMENT,
                                  GL_RENDERBUFFER, 
                                  _depthRenderBuffer);
    }
}

2、visit

主要工作是绘制自建帧缓冲的颜色缓冲内容，以及调用下面的draw，将子节点渲染数据输出到自建帧缓冲。

void RenderTexture::visit(Renderer *renderer, const Mat4 &parentTransform, uint32_t parentFlags)
{
    // override visit.
    // Don't call visit on its children
    if (!_visible)
    {
        return;
    }
    uint32_t flags = processParentFlags(parentTransform, parentFlags);
    Director* director = Director::getInstance();
    // IMPORTANT:
    // To ease the migration to v3.0, we still support the Mat4 stack,
    // but it is deprecated and your code should not rely on it
    director->pushMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_MODELVIEW);
    director->loadMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_MODELVIEW, _modelViewTransform);
    // 将自建帧缓冲当前的颜色缓冲输出到屏幕。
    // 这就是为什么“重定向了”帧缓冲，但是依然能在屏幕上绘制自建缓冲内容的原因。
    // 不明白我说的，请看OpenGL帧缓冲的知识：https://www.yuque.com/tvvhealth/cs/kos5bz#y7my3
    _sprite->visit(renderer, _modelViewTransform, flags);
    if (isVisitableByVisitingCamera())
    {
        draw(renderer, _modelViewTransform, flags);
    }
    director->popMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_MODELVIEW);
    // FIX ME: Why need to set _orderOfArrival to 0??
    // Please refer to https://github.com/cocos2d/cocos2d-x/pull/6920
    // setOrderOfArrival(0);
}

3、draw

将RenderTexture的子节点渲染数据输出到自定义的帧缓冲中。


void RenderTexture::draw(Renderer *renderer, const Mat4 &transform, uint32_t flags)
{
    if (_autoDraw)
    {
        // Begin will create a render group using new render target
        // 创建一个单独RenderQueue，并将RenderQueueID放置绘制栈栈顶，
        // 这样后续的renderCommand都将插入这个RenderQueue。
        // 紧接着在RenderQueue中插入了一个onBegin的CustomCommand，用于在
        // 绘制字节之前，将当前帧缓冲绑定为自定义帧缓存
        begin();
        // 清理默认帧缓冲（screen buffer）的颜色、深度、模板附件
        _clearCommand.init(_globalZOrder);
        _clearCommand.func = CC_CALLBACK_0(RenderTexture::onClear, this);
        renderer->addCommand(&_clearCommand);
        // 子节点排序，localzOrder的升序排序
        sortAllChildren();
        // 绘制子节点，绘制指令都插入的单独RenderQueue，且子节点的渲染数据都将
        // 输出到自定义的帧缓冲中
        for(const auto &child: _children)
        {
            if (child != _sprite)
                child->visit(renderer, transform, flags);
        }
        // 向RenderQueue插入一个onEnd CustomCommand，用于将帧缓冲回复成默认缓冲
        // 然后RenderQueueID从栈顶弹栈，这样后续的RenderCommand将不会再插入这个RenderQueue
        end();
    }
}

4、begin

主要工作

新建RenderQueue
- 用于接收接下来的绘制指令，这样就可以灵活选择需要输出的绘制内容。
onBegin回调
- 在执行指令绘制前的初始化工作
- 这个函数是作为RenderQueue的第一个RenderCommand，保证最前执行 ```cpp

void RenderTexture::begin() { Director* director = Director::getInstance(); CCASSERT(nullptr != director, “Director is null when setting matrix stack”);

director->pushMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_PROJECTION);
_projectionMatrix = director->getMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_PROJECTION);
director->pushMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_MODELVIEW);
_transformMatrix = director->getMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_MODELVIEW);
if(!_keepMatrix)
{
    director->setProjection(director->getProjection());
    const Size& texSize = _texture->getContentSizeInPixels();
    // Calculate the adjustment ratios based on the old and new projections
    Size size = director->getWinSizeInPixels();
    float widthRatio = size.width / texSize.width;
    float heightRatio = size.height / texSize.height;
    Mat4 orthoMatrix;
    Mat4::createOrthographicOffCenter((float)-1.0 / widthRatio, (float)1.0 / widthRatio, (float)-1.0 / heightRatio, (float)1.0 / heightRatio, -1, 1, &orthoMatrix);
    director->multiplyMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_PROJECTION, orthoMatrix);
}
// groupCommand在构造的时候已经指向了一个闲置的空的RenderQueue
// RenderQueue一直都在绘制栈中，必须要有一个groupCommand指向，它里面的renderCommand才会被执行
_groupCommand.init(_globalZOrder);
Renderer *renderer =  Director::getInstance()->getRenderer();
// 执行groupcommand时就是执行RenderQueue的指令。
renderer->addCommand(&_groupCommand);    
// RenderQueue设置在绘制栈顶，后续的绘制指令都将插入这个RenderQueue
renderer->pushGroup(_groupCommand.getRenderQueueID());
// RenderQueue的第一条Command，执行初始化。
_beginCommand.init(_globalZOrder);
_beginCommand.func = CC_CALLBACK_0(RenderTexture::onBegin, this);
Director::getInstance()->getRenderer()->addCommand(&_beginCommand);

}

void RenderTexture::onBegin() { // Director *director = Director::getInstance();

_oldProjMatrix = director->getMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_PROJECTION);
director->loadMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_PROJECTION, _projectionMatrix);
_oldTransMatrix = director->getMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_MODELVIEW);
director->loadMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_MODELVIEW, _transformMatrix);
if(!_keepMatrix)
{
    director->setProjection(director->getProjection());
    const Size& texSize = _texture->getContentSizeInPixels();
    // Calculate the adjustment ratios based on the old and new projections
    Size size = director->getWinSizeInPixels();
    float widthRatio = size.width / texSize.width;
    float heightRatio = size.height / texSize.height;
    Mat4 orthoMatrix;
    Mat4::createOrthographicOffCenter((float)-1.0 / widthRatio, (float)1.0 / widthRatio, (float)-1.0 / heightRatio, (float)1.0 / heightRatio, -1, 1, &orthoMatrix);
    director->multiplyMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_PROJECTION, orthoMatrix);
}
//calculate viewport
{
    Rect viewport;
    viewport.size.width = _fullviewPort.size.width;
    viewport.size.height = _fullviewPort.size.height;
    float viewPortRectWidthRatio = float(viewport.size.width)/_fullRect.size.width;
    float viewPortRectHeightRatio = float(viewport.size.height)/_fullRect.size.height;
    viewport.origin.x = (_fullRect.origin.x - _rtTextureRect.origin.x) * viewPortRectWidthRatio;
    viewport.origin.y = (_fullRect.origin.y - _rtTextureRect.origin.y) * viewPortRectHeightRatio;
    //glViewport(_fullviewPort.origin.x, _fullviewPort.origin.y, (GLsizei)_fullviewPort.size.width, (GLsizei)_fullviewPort.size.height);
    glViewport(viewport.origin.x, viewport.origin.y, (GLsizei)viewport.size.width, (GLsizei)viewport.size.height);
}
glGetIntegerv(GL_FRAMEBUFFER_BINDING, &_oldFBO);    // 保存当前绑定帧缓存
glBindFramebuffer(GL_FRAMEBUFFER, _FBO);            // 设置当前帧缓存为自建的帧缓存
......

}

<a name="1dRSR"></a>
## 5、end
RenderTexure绘制指令接收完毕，RenderQueue不再接收绘制指令，帧缓存恢复成绑定前的帧缓存。
```cpp
void RenderTexture::end()
{
    // 恢复先前绑定的帧缓存，一般就是默认帧缓存。
    _endCommand.init(_globalZOrder);
    _endCommand.func = CC_CALLBACK_0(RenderTexture::onEnd, this);
    Director* director = Director::getInstance();
    CCASSERT(nullptr != director, "Director is null when setting matrix stack");
    // 插入到RenderQueue中的最后一条
    Renderer *renderer = director->getRenderer();
    renderer->addCommand(&_endCommand);
    renderer->popGroup();        //将RenderQueueID弹栈，不再由这个RenderQueue接收绘制指令。
    director->popMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_PROJECTION);
    director->popMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_MODELVIEW);
}
void RenderTexture::onEnd()
{
    Director *director = Director::getInstance();
    glBindFramebuffer(GL_FRAMEBUFFER, _oldFBO);
    // restore viewport
    director->setViewport();
    const auto& vp = Camera::getDefaultViewport();
    glViewport(vp._left, vp._bottom, vp._width, vp._height);
    //
    director->loadMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_PROJECTION, _oldProjMatrix);
    director->loadMatrix(MATRIX_STACK_TYPE::MATRIX_STACK_MODELVIEW, _oldTransMatrix);
}

计算机科学

cocos2dx_RenderTexture