skgpu::graphite::DrawAtlas Class Reference

#include <DrawAtlas.h>

Public Types
enum class	AllowMultitexturing : bool { kNo , kYes }
enum class	ErrorCode { kError , kSucceeded , kTryAgain }

Public Member Functions
ErrorCode	addToAtlas (Recorder *, int width, int height, const void *image, AtlasLocator *)
ErrorCode	addRect (Recorder *, int width, int height, AtlasLocator *)
SkIPoint	prepForRender (const AtlasLocator &, SkAutoPixmapStorage *)
bool	recordUploads (DrawContext *, Recorder *)
const sk_sp< TextureProxy > *	getProxies () const
uint32_t	atlasID () const
uint64_t	atlasGeneration () const
uint32_t	numActivePages () const
unsigned int	numPlots () const
SkISize	plotSize () const
bool	hasID (const PlotLocator &plotLocator)
void	setLastUseToken (const AtlasLocator &atlasLocator, AtlasToken token)
void	setLastUseTokenBulk (const BulkUsePlotUpdater &updater, AtlasToken token)
void	compact (AtlasToken startTokenForNextFlush)
void	evictAllPlots ()
uint32_t	maxPages () const
int	numAllocated_TestingOnly () const
void	setMaxPages_TestingOnly (uint32_t maxPages)

Static Public Member Functions
static std::unique_ptr< DrawAtlas >	Make (SkColorType ct, size_t bpp, int width, int height, int plotWidth, int plotHeight, AtlasGenerationCounter *generationCounter, AllowMultitexturing allowMultitexturing, PlotEvictionCallback *evictor, std::string_view label)

Detailed Description

TODO: the process described here is tentative, and this comment revised once locked down.

This class manages one or more atlas textures on behalf of primitive draws in Device. The drawing processes that use the atlas add preceding UploadTasks when generating RenderPassTasks. The class provides facilities for using DrawTokens to detect data hazards. Plots that need uploads are tracked until it is impossible to add data without overwriting texels read by draws that have not yet been snapped to a RenderPassTask. At that point, the atlas will attempt to allocate a new atlas texture (or "page") of the same size, up to a maximum number of textures, and upload to that texture. If that's not possible, then the atlas will fail to add a subimage. This gives the Device the chance to end the current draw, snap a RenderpassTask, and begin a new one. Additional uploads will then succeed.

When the atlas has multiple pages, new uploads are prioritized to the lower index pages, i.e., it will try to upload to page 0 before page 1 or 2. To keep the atlas from continually using excess space, periodic garbage collection is needed to shift data from the higher index pages to the lower ones, and then eventually remove any pages that are no longer in use. "In use" is determined by using the AtlasToken system: After a DrawPass is snapped a subarea of the page, or "plot" is checked to see whether it was used in that DrawPass. If less than a quarter of the plots have been used recently (within kPlotRecentlyUsedCount iterations) and there are available plots in lower index pages, the higher index page will be deactivated, and its glyphs will gradually migrate to other pages via the usual upload system.

Garbage collection is initiated by the DrawAtlas's client via the compact() method.

Definition at line 53 of file DrawAtlas.h.

Member Enumeration Documentation

AllowMultitexturing

enum class skgpu::graphite::DrawAtlas::AllowMultitexturing : bool

strong

Is the atlas allowed to use more than one texture?

Enumerator
kNo
kYes

Definition at line 56 of file DrawAtlas.h.

: bool { kNo, kYes };

ErrorCode

enum class skgpu::graphite::DrawAtlas::ErrorCode

strong

Adds a width x height subimage to the atlas. Upon success it returns 'kSucceeded' and returns the ID and the subimage's coordinates in the backing texture. 'kTryAgain' is returned if the subimage cannot fit in the atlas without overwriting texels that will be read in the current list of draws. This indicates that the Device should end its current draw, snap a DrawPass, and begin another before adding more data. 'kError' will be returned when some unrecoverable error was encountered while trying to add the subimage. In this case the draw being created should be discarded.

This tracking does not generate UploadTasks per se. Instead, when the RenderPassTask is ready to be snapped, recordUploads() will be called by the Device and that will generate the necessary UploadTasks. If the useCachedUploads argument in recordUploads() is true, this will generate uploads for the entire area of each Plot that has changed since the last eviction. Otherwise it will only generate uploads for newly added changes.

NOTE: When a draw that reads from the atlas is added to the DrawList, the client using this DrawAtlas must immediately call 'setLastUseToken' with the currentToken from the Recorder, otherwise the next call to addToAtlas might cause the previous data to be overwritten before it has been read.

Enumerator
kError
kSucceeded
kTryAgain

Definition at line 101 of file DrawAtlas.h.

                         {
        kError,
        kSucceeded,
        kTryAgain
    };

Member Function Documentation

addRect()

DrawAtlas::ErrorCode skgpu::graphite::DrawAtlas::addRect	(	Recorder *	recorder,
		int	width,
		int	height,
		AtlasLocator *	atlasLocator
	)

Definition at line 185 of file DrawAtlas.cpp.

                                                                    {
    if (width > fPlotWidth || height > fPlotHeight || width < 0 || height < 0) {
        return ErrorCode::kError;
    }
 
    // We permit zero-sized rects to allow inverse fills in the PathAtlases to work,
    // but we don't want to enter them in the Rectanizer. So we handle this special case here.
    // For text this should be caught at a higher level, but if not the only end result
    // will be rendering a degenerate quad.
    if (width == 0 || height == 0) {
        if (fNumActivePages == 0) {
            // Make sure we have a Page for the AtlasLocator to refer to
            this->activateNewPage(recorder);
        }
        atlasLocator->updateRect(skgpu::IRect16::MakeXYWH(0, 0, 0, 0));
        // Use the MRU Plot from the first Page
        atlasLocator->updatePlotLocator(fPages[0].fPlotList.head()->plotLocator());
        return ErrorCode::kSucceeded;
    }
 
    // Look through each page to see if we can upload without having to flush
    // We prioritize this upload to the first pages, not the most recently used, to make it easier
    // to remove unused pages in reverse page order.
    for (unsigned int pageIdx = 0; pageIdx < fNumActivePages; ++pageIdx) {
        if (this->addRectToPage(pageIdx, width, height, atlasLocator)) {
            return ErrorCode::kSucceeded;
        }
    }
 
    // If the above fails, then see if the least recently used plot per page has already been
    // queued for upload if we're at max page allocation, or if the plot has aged out otherwise.
    // We wait until we've grown to the full number of pages to begin evicting already queued
    // plots so that we can maximize the opportunity for reuse.
    // As before we prioritize this upload to the first pages, not the most recently used.
    if (fNumActivePages == this->maxPages()) {
        for (unsigned int pageIdx = 0; pageIdx < fNumActivePages; ++pageIdx) {
            Plot* plot = fPages[pageIdx].fPlotList.tail();
            SkASSERT(plot);
            if (plot->lastUseToken() < recorder->priv().tokenTracker()->nextFlushToken()) {
                this->processEvictionAndResetRects(plot);
                SkDEBUGCODE(bool verify = )plot->addRect(width, height, atlasLocator);
                SkASSERT(verify);
                this->updatePlot(plot, atlasLocator);
                return ErrorCode::kSucceeded;
            }
        }
    } else {
        // If we haven't activated all the available pages, try to create a new one and add to it
        if (!this->activateNewPage(recorder)) {
            return ErrorCode::kError;
        }
 
        if (this->addRectToPage(fNumActivePages-1, width, height, atlasLocator)) {
            return ErrorCode::kSucceeded;
        } else {
            // If we fail to upload to a newly activated page then something has gone terribly
            // wrong - return an error
            return ErrorCode::kError;
        }
    }
 
    if (!fNumActivePages) {
        return ErrorCode::kError;
    }
 
    // All plots are currently in use by the current set of draws, so we need to fail. This
    // gives the Device a chance to snap the current set of uploads and draws, advance the draw
    // token, and call back into this function. The subsequent call will have plots available
    // for fresh uploads.
    return ErrorCode::kTryAgain;
}

addToAtlas()

DrawAtlas::ErrorCode skgpu::graphite::DrawAtlas::addToAtlas	(	Recorder *	recorder,
		int	width,
		int	height,
		const void *	image,
		AtlasLocator *	atlasLocator
	)

Definition at line 259 of file DrawAtlas.cpp.

                                                                       {
    ErrorCode ec = this->addRect(recorder, width, height, atlasLocator);
    if (ec == ErrorCode::kSucceeded) {
        Plot* plot = this->findPlot(*atlasLocator);
        plot->copySubImage(*atlasLocator, image);
    }
 
    return ec;
}

atlasGeneration()

uint64_t skgpu::graphite::DrawAtlas::atlasGeneration ( ) const

inline

Definition at line 117 of file DrawAtlas.h.

{ return fAtlasGeneration; }

atlasID()

uint32_t skgpu::graphite::DrawAtlas::atlasID ( ) const

inline

Definition at line 116 of file DrawAtlas.h.

{ return fAtlasID; }

compact()

void skgpu::graphite::DrawAtlas::compact

(

AtlasToken

startTokenForNextFlush

)

Definition at line 276 of file DrawAtlas.cpp.

                                                         {
    if (fNumActivePages < 1) {
        fPrevFlushToken = startTokenForNextFlush;
        return;
    }
 
    // For all plots, reset number of flushes since used if used this frame.
    PlotList::Iter plotIter;
    bool atlasUsedThisFlush = false;
    for (uint32_t pageIndex = 0; pageIndex < fNumActivePages; ++pageIndex) {
        plotIter.init(fPages[pageIndex].fPlotList, PlotList::Iter::kHead_IterStart);
        while (Plot* plot = plotIter.get()) {
            // Reset number of flushes since used
            if (plot->lastUseToken().inInterval(fPrevFlushToken, startTokenForNextFlush)) {
                plot->resetFlushesSinceLastUsed();
                atlasUsedThisFlush = true;
            }
 
            plotIter.next();
        }
    }
 
    if (atlasUsedThisFlush) {
        fFlushesSinceLastUse = 0;
    } else {
        ++fFlushesSinceLastUse;
    }
 
    // We only try to compact if the atlas was used in the recently completed flush or
    // hasn't been used in a long time.
    // This is to handle the case where a lot of text or path rendering has occurred but then just
    // a blinking cursor is drawn.
    if (atlasUsedThisFlush || fFlushesSinceLastUse > kAtlasRecentlyUsedCount) {
        TArray<Plot*> availablePlots;
        uint32_t lastPageIndex = fNumActivePages - 1;
 
        // For all plots but the last one, update number of flushes since used, and check to see
        // if there are any in the first pages that the last page can safely upload to.
        for (uint32_t pageIndex = 0; pageIndex < lastPageIndex; ++pageIndex) {
            if constexpr (kDumpAtlasData) {
                SkDebugf("page %u: ", pageIndex);
            }
 
            plotIter.init(fPages[pageIndex].fPlotList, PlotList::Iter::kHead_IterStart);
            while (Plot* plot = plotIter.get()) {
                // Update number of flushes since plot was last used
                // We only increment the 'sinceLastUsed' count for flushes where the atlas was used
                // to avoid deleting everything when we return to text drawing in the blinking
                // cursor case
                if (!plot->lastUseToken().inInterval(fPrevFlushToken, startTokenForNextFlush)) {
                    plot->incFlushesSinceLastUsed();
                }
 
                if constexpr (kDumpAtlasData) {
                    SkDebugf("%d ", plot->flushesSinceLastUsed());
                }
 
                // Count plots we can potentially upload to in all pages except the last one
                // (the potential compactee).
                if (plot->flushesSinceLastUsed() > kPlotRecentlyUsedCount) {
                    availablePlots.push_back() = plot;
                }
 
                plotIter.next();
            }
 
            if constexpr (kDumpAtlasData) {
                SkDebugf("\n");
            }
        }
 
        // Count recently used plots in the last page and evict any that are no longer in use.
        // Since we prioritize uploading to the first pages, this will eventually
        // clear out usage of this page unless we have a large need.
        plotIter.init(fPages[lastPageIndex].fPlotList, PlotList::Iter::kHead_IterStart);
        unsigned int usedPlots = 0;
        if constexpr (kDumpAtlasData) {
            SkDebugf("page %u: ", lastPageIndex);
        }
        while (Plot* plot = plotIter.get()) {
            // Update number of flushes since plot was last used
            if (!plot->lastUseToken().inInterval(fPrevFlushToken, startTokenForNextFlush)) {
                plot->incFlushesSinceLastUsed();
            }
 
            if constexpr (kDumpAtlasData) {
                SkDebugf("%d ", plot->flushesSinceLastUsed());
            }
 
            // If this plot was used recently
            if (plot->flushesSinceLastUsed() <= kPlotRecentlyUsedCount) {
                usedPlots++;
            } else if (plot->lastUseToken() != AtlasToken::InvalidToken()) {
                // otherwise if aged out just evict it.
                this->processEvictionAndResetRects(plot);
            }
            plotIter.next();
        }
 
        if constexpr (kDumpAtlasData) {
            SkDebugf("\n");
        }
 
        // If recently used plots in the last page are using less than a quarter of the page, try
        // to evict them if there's available space in lower index pages. Since we prioritize
        // uploading to the first pages, this will eventually clear out usage of this page unless
        // we have a large need.
        if (availablePlots.size() && usedPlots && usedPlots <= fNumPlots / 4) {
            plotIter.init(fPages[lastPageIndex].fPlotList, PlotList::Iter::kHead_IterStart);
            while (Plot* plot = plotIter.get()) {
                // If this plot was used recently
                if (plot->flushesSinceLastUsed() <= kPlotRecentlyUsedCount) {
                    // See if there's room in an lower index page and if so evict.
                    // We need to be somewhat harsh here so that a handful of plots that are
                    // consistently in use don't end up locking the page in memory.
                    if (availablePlots.size() > 0) {
                        this->processEvictionAndResetRects(plot);
                        this->processEvictionAndResetRects(availablePlots.back());
                        availablePlots.pop_back();
                        --usedPlots;
                    }
                    if (!usedPlots || !availablePlots.size()) {
                        break;
                    }
                }
                plotIter.next();
            }
        }
 
        // If none of the plots in the last page have been used recently, delete it.
        if (!usedPlots) {
            if constexpr (kDumpAtlasData) {
                SkDebugf("delete %u\n", fNumActivePages-1);
            }
 
            this->deactivateLastPage();
            fFlushesSinceLastUse = 0;
        }
    }
 
    fPrevFlushToken = startTokenForNextFlush;
}

evictAllPlots()

void skgpu::graphite::DrawAtlas::evictAllPlots

(

)

Definition at line 505 of file DrawAtlas.cpp.

                              {
    PlotList::Iter plotIter;
    for (uint32_t pageIndex = 0; pageIndex < fNumActivePages; ++pageIndex) {
        plotIter.init(fPages[pageIndex].fPlotList, PlotList::Iter::kHead_IterStart);
        while (Plot* plot = plotIter.get()) {
            this->processEvictionAndResetRects(plot);
            plotIter.next();
        }
    }
}

getProxies()

const sk_sp< TextureProxy > * skgpu::graphite::DrawAtlas::getProxies ( ) const

inline

Definition at line 114 of file DrawAtlas.h.

{ return fProxies; }

hasID()

bool skgpu::graphite::DrawAtlas::hasID ( const PlotLocator &  plotLocator )

inline

Definition at line 122 of file DrawAtlas.h.

                                               {
        if (!plotLocator.isValid()) {
            return false;
        }
 
        uint32_t plot = plotLocator.plotIndex();
        uint32_t page = plotLocator.pageIndex();
        uint64_t plotGeneration = fPages[page].fPlotArray[plot]->genID();
        uint64_t locatorGeneration = plotLocator.genID();
        return plot < fNumPlots && page < fNumActivePages && plotGeneration == locatorGeneration;
    }

Make()

std::unique_ptr< DrawAtlas > skgpu::graphite::DrawAtlas::Make ( SkColorType  ct, size_t  bpp, int  width, int  height, int  plotWidth, int  plotHeight, AtlasGenerationCounter *  generationCounter, AllowMultitexturing  allowMultitexturing, PlotEvictionCallback *  evictor, std::string_view  label  )

static

Returns a DrawAtlas.

Parameters

ct	The colorType which this atlas will store.
bpp	Size in bytes of each pixel.
width	Width in pixels of the atlas.
height	Height in pixels of the atlas.
plotWidth	The width of each plot. width/plotWidth should be an integer.
plotWidth	The height of each plot. height/plotHeight should be an integer.
atlasGeneration	A pointer to the context's generation counter.
allowMultitexturing	Can the atlas use more than one texture.
evictor	A pointer to an eviction callback class.

Returns

An initialized DrawAtlas, or nullptr if creation fails.

Definition at line 52 of file DrawAtlas.cpp.

                                                                 {
    std::unique_ptr<DrawAtlas> atlas(new DrawAtlas(colorType, bpp, width, height,
                                                   plotWidth, plotHeight, generationCounter,
                                                   allowMultitexturing, label));
 
    if (evictor != nullptr) {
        atlas->fEvictionCallbacks.emplace_back(evictor);
    }
    return atlas;
}

maxPages()

uint32_t skgpu::graphite::DrawAtlas::maxPages ( ) const

inline

Definition at line 158 of file DrawAtlas.h.

                              {
        return fMaxPages;
    }

numActivePages()

uint32_t skgpu::graphite::DrawAtlas::numActivePages ( ) const

inline

Definition at line 118 of file DrawAtlas.h.

{ return fNumActivePages; }

numAllocated_TestingOnly()

int skgpu::graphite::DrawAtlas::numAllocated_TestingOnly

(

)

const

numPlots()

unsigned int skgpu::graphite::DrawAtlas::numPlots ( ) const

inline

Definition at line 119 of file DrawAtlas.h.

{ return fNumPlots; }

plotSize()

SkISize skgpu::graphite::DrawAtlas::plotSize ( ) const

inline

Definition at line 120 of file DrawAtlas.h.

{ return {fPlotWidth, fPlotHeight}; }

prepForRender()

SkIPoint skgpu::graphite::DrawAtlas::prepForRender	(	const AtlasLocator &	locator,
		SkAutoPixmapStorage *	pixmap
	)

Definition at line 271 of file DrawAtlas.cpp.

                                                                                          {
    Plot* plot = this->findPlot(locator);
    return plot->prepForRender(locator, pixmap);
}

recordUploads()

bool skgpu::graphite::DrawAtlas::recordUploads	(	DrawContext *	dc,
		Recorder *	recorder
	)

Definition at line 144 of file DrawAtlas.cpp.

                                                                 {
    TRACE_EVENT0("skia.gpu", TRACE_FUNC);
    for (uint32_t pageIdx = 0; pageIdx < fNumActivePages; ++pageIdx) {
        PlotList::Iter plotIter;
        plotIter.init(fPages[pageIdx].fPlotList, PlotList::Iter::kHead_IterStart);
        for (Plot* plot = plotIter.get(); plot; plot = plotIter.next()) {
            if (plot->needsUpload()) {
                TextureProxy* proxy = fProxies[pageIdx].get();
                SkASSERT(proxy);
 
                const void* dataPtr;
                SkIRect dstRect;
                std::tie(dataPtr, dstRect) = plot->prepareForUpload();
                if (dstRect.isEmpty()) {
                    continue;
                }
 
                std::vector<MipLevel> levels;
                levels.push_back({dataPtr, fBytesPerPixel*fPlotWidth});
 
                // Src and dst colorInfo are the same
                SkColorInfo colorInfo(fColorType, kUnknown_SkAlphaType, nullptr);
                if (!dc->recordUpload(recorder, sk_ref_sp(proxy), colorInfo, colorInfo, levels,
                                      dstRect, /*ConditionalUploadContext=*/nullptr)) {
                    return false;
                }
            }
        }
    }
    return true;
}

setLastUseToken()

void skgpu::graphite::DrawAtlas::setLastUseToken ( const AtlasLocator &  atlasLocator, AtlasToken  token  )

inline

To ensure the atlas does not evict a given entry, the client must set the last use token.

Definition at line 135 of file DrawAtlas.h.

                                                                             {
        Plot* plot = this->findPlot(atlasLocator);
        this->internalSetLastUseToken(plot, atlasLocator.pageIndex(), token);
    }

setLastUseTokenBulk()

void skgpu::graphite::DrawAtlas::setLastUseTokenBulk ( const BulkUsePlotUpdater &  updater, AtlasToken  token  )

inline

Definition at line 140 of file DrawAtlas.h.

                                               {
        int count = updater.count();
        for (int i = 0; i < count; i++) {
            const BulkUsePlotUpdater::PlotData& pd = updater.plotData(i);
            // it's possible we've added a plot to the updater and subsequently the plot's page
            // was deleted -- so we check to prevent a crash
            if (pd.fPageIndex < fNumActivePages) {
                Plot* plot = fPages[pd.fPageIndex].fPlotArray[pd.fPlotIndex].get();
                this->internalSetLastUseToken(plot, pd.fPageIndex, token);
            }
        }
    }

setMaxPages_TestingOnly()

void skgpu::graphite::DrawAtlas::setMaxPages_TestingOnly

(

uint32_t

maxPages

)

---

The documentation for this class was generated from the following files:

• third_party/skia/src/gpu/graphite/DrawAtlas.h
• third_party/skia/src/gpu/graphite/DrawAtlas.cpp