GrDrawOpAtlas Class Reference

#include <GrDrawOpAtlas.h>

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

Public Member Functions
ErrorCode	addToAtlas (GrResourceProvider *, GrDeferredUploadTarget *, int width, int height, const void *image, skgpu::AtlasLocator *)
const GrSurfaceProxyView *	getViews () const
uint64_t	atlasGeneration () const
bool	hasID (const skgpu::PlotLocator &plotLocator)
void	setLastUseToken (const skgpu::AtlasLocator &atlasLocator, skgpu::AtlasToken token)
uint32_t	numActivePages ()
void	setLastUseTokenBulk (const skgpu::BulkUsePlotUpdater &updater, skgpu::AtlasToken token)
void	compact (skgpu::AtlasToken startTokenForNextFlush)
void	instantiate (GrOnFlushResourceProvider *)
uint32_t	maxPages () const

Static Public Member Functions
static std::unique_ptr< GrDrawOpAtlas >	Make (GrProxyProvider *proxyProvider, const GrBackendFormat &format, SkColorType ct, size_t bpp, int width, int height, int plotWidth, int plotHeight, skgpu::AtlasGenerationCounter *generationCounter, AllowMultitexturing allowMultitexturing, skgpu::PlotEvictionCallback *evictor, std::string_view label)

Friends
class	GrDrawOpAtlasTools

Detailed Description

This class manages one or more atlas textures on behalf of GrDrawOps. The draw ops that use the atlas perform texture uploads when preparing their draws during flush. The class provides facilities for using GrDrawOpUploadToken to detect data hazards. Op's uploads are performed in "ASAP" mode until it is impossible to add data without overwriting texels read by draws that have not yet executed on the gpu. 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, the uploads are performed "inline" between draws. If a single draw would use enough subimage space to overflow the atlas texture then the atlas will fail to add a subimage. This gives the op the chance to end the draw and begin a new one. Additional uploads will then succeed in inline mode.

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 GrDrawUploadToken system: After a flush each subarea of the page is checked to see whether it was used in that flush. 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 GrDrawOpAtlas's client via the compact() method. One solution is to make the client a subclass of GrOnFlushCallbackObject, register it with the GrContext via addOnFlushCallbackObject(), and the client's postFlush() method calls compact() and passes in the given GrDrawUploadToken.

Definition at line 53 of file GrDrawOpAtlas.h.

Member Enumeration Documentation

AllowMultitexturing

enum class GrDrawOpAtlas::AllowMultitexturing : bool

strong

Is the atlas allowed to use more than one texture?

Enumerator
kNo
kYes

Definition at line 56 of file GrDrawOpAtlas.h.

: bool { kNo, kYes };

ErrorCode

enum class GrDrawOpAtlas::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 draw. This indicates that the op should end its current draw and begin another before adding more data. Upon success, an upload of the provided image data will have been added to the GrDrawOp::Target, in "asap" mode if possible, otherwise in "inline" mode. Successive uploads in either mode may be consolidated. 'kError' will be returned when some unrecoverable error was encountered while trying to add the subimage. In this case the op being created should be discarded.

NOTE: When the GrDrawOp prepares a draw that reads from the atlas, it must immediately call 'setLastUseToken' with the currentToken from the GrDrawOp::Target, 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 103 of file GrDrawOpAtlas.h.

                         {
        kError,
        kSucceeded,
        kTryAgain
    };

Member Function Documentation

addToAtlas()

GrDrawOpAtlas::ErrorCode GrDrawOpAtlas::addToAtlas	(	GrResourceProvider *	resourceProvider,
		GrDeferredUploadTarget *	target,
		int	width,
		int	height,
		const void *	image,
		skgpu::AtlasLocator *	atlasLocator
	)

Definition at line 209 of file GrDrawOpAtlas.cpp.

                                                                               {
    if (width > fPlotWidth || height > fPlotHeight) {
        return ErrorCode::kError;
    }
 
    // 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->uploadToPage(pageIdx, target, width, height, image, atlasLocator)) {
            return ErrorCode::kSucceeded;
        }
    }
 
    // If the above fails, then see if the least recently used plot per page has already been
    // flushed to the gpu 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 flushed
    // 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() < target->tokenTracker()->nextFlushToken()) {
                this->processEvictionAndResetRects(plot);
                SkASSERT(GrBackendFormatBytesPerPixel(fViews[pageIdx].proxy()->backendFormat()) ==
                         plot->bpp());
                SkDEBUGCODE(bool verify = )plot->addSubImage(width, height, image, atlasLocator);
                SkASSERT(verify);
                if (!this->updatePlot(target, atlasLocator, plot)) {
                    return ErrorCode::kError;
                }
                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(resourceProvider)) {
            return ErrorCode::kError;
        }
 
        if (this->uploadToPage(fNumActivePages-1, target, width, height, image, 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;
    }
 
    // Try to find a plot that we can perform an inline upload to.
    // We prioritize this upload in reverse order of pages to counterbalance the order above.
    Plot* plot = nullptr;
    for (int pageIdx = ((int)fNumActivePages)-1; pageIdx >= 0; --pageIdx) {
        Plot* currentPlot = fPages[pageIdx].fPlotList.tail();
        if (currentPlot->lastUseToken() != target->tokenTracker()->nextDrawToken()) {
            plot = currentPlot;
            break;
        }
    }
 
    // If we can't find a plot that is not used in a draw currently being prepared by an op, then
    // we have to fail. This gives the op a chance to enqueue the draw, and call back into this
    // function. When that draw is enqueued, the draw token advances, and the subsequent call will
    // continue past this branch and prepare an inline upload that will occur after the enqueued
    // draw which references the plot's pre-upload content.
    if (!plot) {
        return ErrorCode::kTryAgain;
    }
 
    this->processEviction(plot->plotLocator());
    int pageIdx = plot->pageIndex();
    fPages[pageIdx].fPlotList.remove(plot);
    sk_sp<Plot>& newPlot = fPages[pageIdx].fPlotArray[plot->plotIndex()];
    newPlot = plot->clone();
 
    fPages[pageIdx].fPlotList.addToHead(newPlot.get());
    SkASSERT(GrBackendFormatBytesPerPixel(fViews[pageIdx].proxy()->backendFormat()) ==
             newPlot->bpp());
    SkDEBUGCODE(bool verify = )newPlot->addSubImage(width, height, image, atlasLocator);
    SkASSERT(verify);
 
    // Note that this plot will be uploaded inline with the draws whereas the
    // one it displaced most likely was uploaded ASAP.
    // With c++14 we could move sk_sp into lambda to only ref once.
    sk_sp<Plot> plotsp(SkRef(newPlot.get()));
 
    GrTextureProxy* proxy = fViews[pageIdx].asTextureProxy();
    SkASSERT(proxy && proxy->isInstantiated());
 
    AtlasToken lastUploadToken = target->addInlineUpload(
            [this, plotsp, proxy](GrDeferredTextureUploadWritePixelsFn& writePixels) {
                this->uploadPlotToTexture(writePixels, proxy, plotsp.get());
            });
    newPlot->setLastUploadToken(lastUploadToken);
 
    atlasLocator->updatePlotLocator(newPlot->plotLocator());
    SkDEBUGCODE(this->validate(*atlasLocator);)
 
    return ErrorCode::kSucceeded;
}

atlasGeneration()

uint64_t GrDrawOpAtlas::atlasGeneration ( ) const

inline

Definition at line 114 of file GrDrawOpAtlas.h.

{ return fAtlasGeneration; }

compact()

void GrDrawOpAtlas::compact

(

skgpu::AtlasToken

startTokenForNextFlush

)

Definition at line 318 of file GrDrawOpAtlas.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 earlier 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.empty() && 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 earlier 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.empty()) {
                        this->processEvictionAndResetRects(plot);
                        this->processEvictionAndResetRects(availablePlots.back());
                        availablePlots.pop_back();
                        --usedPlots;
                    }
                    if (!usedPlots || availablePlots.empty()) {
                        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;
}

getViews()

const GrSurfaceProxyView * GrDrawOpAtlas::getViews ( ) const

inline

Definition at line 112 of file GrDrawOpAtlas.h.

{ return fViews; }

hasID()

bool GrDrawOpAtlas::hasID ( const skgpu::PlotLocator &  plotLocator )

inline

Definition at line 116 of file GrDrawOpAtlas.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;
    }

instantiate()

void GrDrawOpAtlas::instantiate

(

GrOnFlushResourceProvider *

onFlushResourceProvider

)

Definition at line 63 of file GrDrawOpAtlas.cpp.

                                                                                  {
    for (uint32_t i = 0; i < fNumActivePages; ++i) {
        // All the atlas pages are now instantiated at flush time in the activeNewPage method.
        SkASSERT(fViews[i].proxy() && fViews[i].proxy()->isInstantiated());
    }
}

Make()

std::unique_ptr< GrDrawOpAtlas > GrDrawOpAtlas::Make ( GrProxyProvider *  proxyProvider, const GrBackendFormat &  format, SkColorType  ct, size_t  bpp, int  width, int  height, int  plotWidth, int  plotHeight, skgpu::AtlasGenerationCounter *  generationCounter, AllowMultitexturing  allowMultitexturing, skgpu::PlotEvictionCallback *  evictor, std::string_view  label  )

static

Returns a GrDrawOpAtlas. This function can be called anywhere, but the returned atlas should only be used inside of GrMeshDrawOp::onPrepareDraws.

Parameters

proxyProvider	Used to create the atlas's texture proxies.
format	Backend format for the atlas's textures. Should be compatible with ct.
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.
generationCounter	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.
label	A label for the atlas texture.

Returns

An initialized DrawAtlas, or nullptr if creation fails.

Definition at line 70 of file GrDrawOpAtlas.cpp.

                                                                         {
    if (!format.isValid()) {
        return nullptr;
    }
 
    std::unique_ptr<GrDrawOpAtlas> atlas(new GrDrawOpAtlas(proxyProvider, format, colorType, bpp,
                                                           width, height, plotWidth, plotHeight,
                                                           generationCounter,
                                                           allowMultitexturing, label));
    if (!atlas->createPages(proxyProvider, generationCounter) || !atlas->getViews()[0].proxy()) {
        return nullptr;
    }
 
    if (evictor != nullptr) {
        atlas->fEvictionCallbacks.emplace_back(evictor);
    }
    return atlas;
}

maxPages()

uint32_t GrDrawOpAtlas::maxPages ( ) const

inline

Definition at line 161 of file GrDrawOpAtlas.h.

                              {
        return fMaxPages;
    }

numActivePages()

uint32_t GrDrawOpAtlas::numActivePages ( )

inline

Definition at line 140 of file GrDrawOpAtlas.h.

{ return fNumActivePages; }

setLastUseToken()

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

inline

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

Definition at line 129 of file GrDrawOpAtlas.h.

                                                                                       {
        SkASSERT(this->hasID(atlasLocator.plotLocator()));
        uint32_t plotIdx = atlasLocator.plotIndex();
        SkASSERT(plotIdx < fNumPlots);
        uint32_t pageIdx = atlasLocator.pageIndex();
        SkASSERT(pageIdx < fNumActivePages);
        skgpu::Plot* plot = fPages[pageIdx].fPlotArray[plotIdx].get();
        this->makeMRU(plot, pageIdx);
        plot->setLastUseToken(token);
    }

setLastUseTokenBulk()

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

inline

Definition at line 142 of file GrDrawOpAtlas.h.

                                                    {
        int count = updater.count();
        for (int i = 0; i < count; i++) {
            const skgpu::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) {
                skgpu::Plot* plot = fPages[pd.fPageIndex].fPlotArray[pd.fPlotIndex].get();
                this->makeMRU(plot, pd.fPageIndex);
                plot->setLastUseToken(token);
            }
        }
    }

Friends And Related Function Documentation

GrDrawOpAtlasTools

friend class GrDrawOpAtlasTools

friend

Definition at line 166 of file GrDrawOpAtlas.h.

---

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

• third_party/skia/src/gpu/ganesh/GrDrawOpAtlas.h
• third_party/skia/src/gpu/ganesh/GrDrawOpAtlas.cpp