RIV — API & Interfaces

Contract Hand back a ref-counted (rcp) render resource for each make* the runtime issues while building a scene — a path, an empty path, a paint, a linear/radial gradient shader, or a vertex/index buffer — and decode in-band image bytes to a RenderImage. The runtime owns lifetimes through the rcp; you choose the concrete representation. decodeImage may return null on failure.

Ours The object factory the runtime calls during File::import to materialise every render resource for the "ours" route. Each make* wraps the matching SimpleRender* in an rcp via make_rcp, keeping gradients as CPU stop data rather than baking them. decodeImage runs Rive's own bundled Bitmap decoder, forces premultiplied RGBA8 (so GL_LINEAR is correct at transparent edges), then uploads straight to a GL texture — a GL context is already current during import.

SimpleShapeFactory::decodeImage — reuse Rive's decoder, then upload to GL

rive::rcp<rive::RenderImage> decodeImage(rive::Span<const uint8_t> span) override
{
    // Decode PNG/JPEG/WebP with Rive's bundled Bitmap decoder, force PREMULTIPLIED
    // RGBA8 (like the official runtime), then wrap a GL texture in SimpleRenderImage.
    auto bmp = Bitmap::decode(span.data(), span.size());
    if (!bmp) return nullptr;
    if (bmp->pixelFormat() != Bitmap::PixelFormat::RGBAPremul)
        bmp->pixelFormat(Bitmap::PixelFormat::RGBAPremul);
    return rive::make_rcp<SimpleRenderImage>(bmp->bytes(), bmp->width(), bmp->height());
}

Contract Maintain a transform / clip / opacity state stack (save / restore / transform / modulateOpacity) and execute the draw commands the runtime issues against it — drawPath(path, paint), clipPath(path), drawImage, drawImageMesh — producing pixels however you like. The runtime hands you its own RenderPath/RenderPaint pointers; you downcast to read them.

Ours The draw-command sink the runtime issues into. It owns a transform / opacity / clip State stack (save/restore/transform/ modulateOpacity push and mutate the back entry). drawPath downcasts the path & paint to our concretes, flattens the RawPath into device-space contours under the current transform, then dispatches to a GlShapePipeline (solid / gradient / feathered fills, tessellated strokes) that does the actual GPU stencil-then-cover into an MSAA FBO. clipPath pushes a flattened device-space clip layer (non-convex stencil intersection). It also carries side-channel aux modes (id / depth / velocity / bounds / contour) that re-purpose the same draws for the NPR post-process — something the official renderer can't feed.

The save/restore/transform/opacity State-stack that backs the adapter

void save() override    { m_stack.push_back(m_stack.back()); }
void restore() override { if (m_stack.size() > 1) m_stack.pop_back(); }
void transform(const rive::Mat2D& t) override
{
    m_stack.back().transform = m_stack.back().transform * t;
}
void modulateOpacity(float o) override { m_stack.back().opacity *= o; }

Contract Accumulate path geometry: the verb stream (moveTo / lineTo / cubicTo / close), a fill rule, and combiners that append other paths or a raw path under a transform (addRenderPath, addRenderPathBackwards, addRawPath); rewind clears it. The runtime never asks you to rasterize — only to hold the geometry until it issues a drawPath.

Ours Geometry is stored purely on the CPU as a rive::RawPath + a FillRule — there is no tessellation at build time. The verb overrides (moveTo/lineTo/cubicTo/close) and the add*Path combiners forward straight into the held RawPath, baking the supplied Mat2D via RawPath::addPath(&transform) and downcasting to recover the concrete when merging two paths. The renderer reads rawPath()/fillRuleValue() and flattens to device-space polylines only at draw time.

Verb & combiner overrides forwarding into the held RawPath

void moveTo(float x, float y) override { m_path.moveTo(x, y); }
void lineTo(float x, float y) override { m_path.lineTo(x, y); }
void addRenderPath(const rive::RenderPath* p, const rive::Mat2D& m) override
{
    if (auto* s = dynamic_cast<const SimpleRenderPath*>(p))
        m_path.addPath(s->rawPath(), &m);   // bake the transform into our RawPath
}

Contract Capture the paint state the runtime sets: style (fill / stroke), color, stroke thickness / join / cap, feather strength, blend mode, and an optional gradient shader. invalidateStroke signals stroke geometry should be rebuilt. Pure data — the interface never draws.

Ours A plain CPU value-object: every setter stashes its argument into a member (style, color, thickness, join, cap, feather, blend mode, optional shader); invalidateStroke is a no-op because no stroke geometry is cached here. Accessors expose those to the renderer — colorValue() even folds a bound gradient down to a representative average so a solid-color path always has something usable, while shaderValue() downcasts back to SimpleRenderShader for full gradient reconstruction.

Contract Be an opaque gradient handle. The runtime constructs you via Factory::makeLinearGradient / makeRadialGradient (endpoints or centre + radius, plus parallel color and stop-position arrays) and hands you back through RenderPaint::shader. The base declares no virtuals — you decide how to store and later sample the gradient.

Ours RenderShader is an opaque marker base in Rive — no virtuals to override — so the gradient lives as data: a kind (linear/radial), start/end points, a radius, and a sorted, clamped vector of (position, color) stops captured from the factory's arrays. The renderer either feeds those stops to the GL gradient program in object space (with the device→object inverse, so radial gradients stay elliptical under rotation), or — for the CPU/ImGui path — evaluates a screen point against the stops by bracketing and colorLerp.

Gradient kept as stop data, evaluated by bracketing + colorLerp

rive::ColorInt sampleAt(float position) const
{
    if (position <= m_stops.front().position) return m_stops.front().color;
    if (position >= m_stops.back().position)  return m_stops.back().color;
    for (size_t i = 1; i < m_stops.size(); ++i)
        if (position <= m_stops[i].position) {
            float t = (position - m_stops[i-1].position) /
                      (m_stops[i].position - m_stops[i-1].position);
            return rive::colorLerp(m_stops[i-1].color, m_stops[i].color, t);
        }
    return m_stops.back().color;
}

Contract Back a typed buffer (vertex / index, sized in bytes from the base ctor) for image meshes. The runtime writes into it through the map protocol: onMap returns a writable pointer, onUnmap finalises the write (upload to GPU if you need to). You keep the contents readable at draw time.

Ours Vertex / UV / index buffers for image meshes are just a heap std::vector<uint8_t> sized to the requested byte count. The runtime fills it through the map/unmap protocol — onMap hands back the raw pointer, onUnmap is a no-op (no GPU upload), so the bytes simply live in CPU memory. At draw time drawImageMesh reads bytes()/byteSize() to expand the mesh into device-space triangles.

Contract Wrap a decoded bitmap as a drawable image and report its width / height (base members). The runtime hands you premultiplied RGBA8 from Factory::decodeImage; you own the GPU upload and the texture's lifetime, and expose whatever handle your Renderer needs to bind it.

Ours An image is one GL texture. The ctor receives tightly-packed premultiplied RGBA8, sets the base RenderImage width/height members, then glGenTextures + glTexImage2D uploads it as GL_RGBA8 with linear filtering and clamp-to-edge wrap. The destructor frees the texture; textureId() exposes the handle for the renderer's textured-quad / mesh draws.

Premultiplied RGBA8 → a GL_RGBA8 texture (linear, clamp-to-edge)

SimpleRenderImage(const uint8_t* rgba, int w, int h)
{
    m_Width = w; m_Height = h;            // base rive::RenderImage members
    glGenTextures(1, &m_tex);
    glBindTexture(GL_TEXTURE_2D, m_tex);
    glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA8, w, h, 0, GL_RGBA,
                 GL_UNSIGNED_BYTE, rgba);
    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
}