GrContext

class GrContext

Methods

ComputeImageSize

__init__

abandonContext

Abandons all GPU resources and assumes the underlying backend 3D API context is no longer usable.

abandoned

Returns true if the context was abandoned or if the if the backend specific context has gotten into an unrecoverarble, lost state (e.g.

asDirectContext

Safely downcast to a GrDirectContext.

backend

The 3D API backing this context.

checkAsyncWorkCompletion

Checks whether any asynchronous work is complete and if so calls related callbacks.

colorTypeSupportedAsImage

Can a Image be created with the given color type.

colorTypeSupportedAsSurface

Can a SkSurface be created with the given color type.

compressedBackendFormat

Retrieve the GrBackendFormat for a given Image.CompressionType.

createBackendTexture

Overloaded function.

createCompressedBackendTexture

Overloaded function.

defaultBackendFormat

Retrieve the default GrBackendFormat for a given ColorType and renderability.

deleteBackendTexture

flush

Overloaded function.

flushAndSubmit

Call to ensure all drawing to the context has been flushed and submitted to the underlying 3D API.

freeGpuResources

Frees GPU created by the context.

getResourceCacheLimit

Return the current GPU resource cache limit in bytes.

getResourceCachePurgeableBytes

Gets the number of bytes in the cache consumed by purgeable (e.g.

getResourceCacheUsage

Gets the current GPU resource cache usage.

maxRenderTargetSize

Gets the maximum supported render target size.

maxSurfaceSampleCountForColorType

Gets the maximum supported sample count for a color type.

maxTextureSize

Gets the maximum supported texture size.

oomed

Checks if the underlying 3D API reported an out-of-memory error.

performDeferredCleanup

Purge GPU resources that haven’t been used in the past ‘msNotUsed’ milliseconds or are otherwise marked for deletion, regardless of whether the context is under budget.

precompileShader

purgeResourcesNotUsedInMs

purgeUnlockedResources

Overloaded function.

ref

Increment the reference count.

releaseResourcesAndAbandonContext

This is similar to abandonContext() however the underlying 3D context is not yet lost and the GrContext will cleanup all allocated resources before returning.

resetContext

The GrContext normally assumes that no outsider is setting state within the underlying 3D API’s context/device/whatever.

resetGLTextureBindings

If the backend is kOpenGL, then all texture unit/target combinations for which the GrContext has modified the bound texture will have texture id 0 bound.

setBackendRenderTargetState

setBackendTextureState

Updates the state of the GrBackendTexture/RenderTarget to have the passed in GrBackendSurfaceMutableState.

setResourceCacheLimit

Specify the GPU resource cache limit.

storeVkPipelineCacheData

submit

Submit outstanding work to the gpu from all previously un-submitted flushes.

supportsDistanceFieldText

threadSafeProxy

unique

May return true if the caller is the only owner.

unref

Decrement the reference count.

updateBackendTexture

Overloaded function.

wait

Inserts a list of GPU semaphores that the current GPU-backed API must wait on before executing any more commands on the GPU.

Methods

static GrContext.ComputeImageSize(image: SkImage, mipMapped: skia.GrMipmapped, useNextPow2: bool = False) int
GrContext.__init__(*args, **kwargs)
GrContext.abandonContext(self: skia.GrContext) None

Abandons all GPU resources and assumes the underlying backend 3D API context is no longer usable.

Call this if you have lost the associated GPU context, and thus internal texture, buffer, etc. references/IDs are now invalid. Calling this ensures that the destructors of the GrContext and any of its created resource objects will not make backend 3D API calls. Content rendered but not previously flushed may be lost. After this function is called all subsequent calls on the GrContext will fail or be no-ops.

The typical use case for this function is that the underlying 3D context was lost and further API calls may crash.

For Vulkan, even if the device becomes lost, the VkQueue, VkDevice, or VkInstance used to create the GrContext must be alive before calling abandonContext.

GrContext.abandoned(self: skia.GrContext) bool

Returns true if the context was abandoned or if the if the backend specific context has gotten into an unrecoverarble, lost state (e.g.

in Vulkan backend if we’ve gotten a VK_ERROR_DEVICE_LOST). If the backend context is lost, this call will also abandon the GrContext.

GrContext.asDirectContext(self: skia.GrContext_Base) GrDirectContext

Safely downcast to a GrDirectContext.

GrContext.backend(self: skia.GrContext_Base) skia.GrBackendApi

The 3D API backing this context.

GrContext.checkAsyncWorkCompletion(self: skia.GrContext) None

Checks whether any asynchronous work is complete and if so calls related callbacks.

GrContext.colorTypeSupportedAsImage(self: skia.GrContext, colorType: SkColorType) bool

Can a Image be created with the given color type.

GrContext.colorTypeSupportedAsSurface(self: skia.GrContext, colorType: SkColorType) bool

Can a SkSurface be created with the given color type.

To check whether MSAA is supported use maxSurfaceSampleCountForColorType().

GrContext.compressedBackendFormat(self: skia.GrContext, compressionType: SkImage::CompressionType) skia.GrBackendFormat

Retrieve the GrBackendFormat for a given Image.CompressionType.

This is guaranteed to match the backend format used by the following createCompressedsBackendTexture() methods that take a CompressionType. The caller should check that the returned format is valid.

GrContext.createBackendTexture(*args, **kwargs)

Overloaded function.

  1. createBackendTexture(self: skia.GrContext, width: int, height: int, backendFormat: skia.GrBackendFormat, mipMapped: skia.GrMipmapped, renderable: skia.GrRenderable, isProtected: skia.GrProtected = <GrProtected.kNo: 0>) -> skia.GrBackendTexture

    If possible, create an uninitialized backend texture.

    The client should ensure that the returned backend texture is valid. For the Vulkan backend the layout of the created VkImage will be:

    VK_IMAGE_LAYOUT_UNDEFINED.

  2. createBackendTexture(self: skia.GrContext, width: int, height: int, colorType: SkColorType, mipMapped: skia.GrMipmapped, renderable: skia.GrRenderable, isProtected: skia.GrProtected = <GrProtected.kNo: 0>) -> skia.GrBackendTexture

    If possible, create an uninitialized backend texture.

    The client should ensure that the returned backend texture is valid. If successful, the created backend texture will be compatible with the provided ColorType. For the Vulkan backend the layout of the created VkImage will be: VK_IMAGE_LAYOUT_UNDEFINED.

  3. createBackendTexture(self: skia.GrContext, width: int, height: int, backendFormat: skia.GrBackendFormat, color: skia.Color4f, mipMapped: skia.GrMipmapped, renderable: skia.GrRenderable, isProtected: skia.GrProtected = <GrProtected.kNo: 0>) -> skia.GrBackendTexture

    If possible, create a backend texture initialized to a particular color.

    The client should ensure that the returned backend texture is valid. The client can pass in a finishedProc to be notified when the data has been uploaded by the gpu and the texture can be deleted. The client is required to call GrContext::submit to send the upload work to the gpu. The finishedProc will always get called even if we failed to create the GrBackendTexture. For the Vulkan backend the layout of the created VkImage will be:

    VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  4. createBackendTexture(self: skia.GrContext, width: int, height: int, colorType: SkColorType, color: skia.Color4f, mipMapped: skia.GrMipmapped, renderable: skia.GrRenderable, isProtected: skia.GrProtected = <GrProtected.kNo: 0>) -> skia.GrBackendTexture

    If possible, create a backend texture initialized to a particular color.

    The client should ensure that the returned backend texture is valid. If successful, the created backend texture will be compatible with the provided ColorType. For the Vulkan backend the layout of the created VkImage will be: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  5. createBackendTexture(self: skia.GrContext, srcData: List[SkPixmap], renderable: skia.GrRenderable, isProtected: skia.GrProtected = <GrProtected.kNo: 0>) -> skia.GrBackendTexture

    If possible, create a backend texture initialized with the provided pixmap data. The client should ensure that the returned backend texture is valid. The client can pass in a finishedProc to be notified when the data has been uploaded by the gpu and the texture can be deleted. The client is required to call GrContext::submit to send the upload work to the gpu. The finishedProc will always get called even if we failed to create the GrBackendTexture. If successful, the created backend texture will be compatible with the provided pixmap(s). Compatible, in this case, means that the backend format will be the result of calling defaultBackendFormat on the base pixmap’s colortype. The src data can be deleted when this call returns.

    If numLevels is 1 a non-mipMapped texture will result. If a mipMapped texture is desired the data for all the mipmap levels must be provided. In the mipmapped case all the colortypes of the provided pixmaps must be the same. Additionally, all the miplevels must be sized correctly (please see SkMipmap::ComputeLevelSize and ComputeLevelCount). Note: the pixmap’s alphatypes and colorspaces are ignored. For the Vulkan backend the layout of the created VkImage will be: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  6. createBackendTexture(self: skia.GrContext, pixmap: SkPixmap, renderable: skia.GrRenderable, isProtected: skia.GrProtected = <GrProtected.kNo: 0>) -> skia.GrBackendTexture

GrContext.createCompressedBackendTexture(*args, **kwargs)

Overloaded function.

  1. createCompressedBackendTexture(self: skia.GrContext, width: int, height: int, backendFormat: skia.GrBackendFormat, color: skia.Color4f, mipMapped: skia.GrMipmapped, isProtected: skia.GrProtected = <GrProtected.kNo: 0>) -> skia.GrBackendTexture

    If possible, create a compressed backend texture initialized to a particular color.

    The client should ensure that the returned backend texture is valid. For the Vulkan backend the layout of the created VkImage will be: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  2. createCompressedBackendTexture(self: skia.GrContext, width: int, height: int, type: SkImage::CompressionType, color: skia.Color4f, mipMapped: skia.GrMipmapped, isProtected: skia.GrProtected = <GrProtected.kNo: 0>) -> skia.GrBackendTexture

  3. createCompressedBackendTexture(self: skia.GrContext, width: int, height: int, backendFormat: skia.GrBackendFormat, data: buffer, mipMapped: skia.GrMipmapped, isProtected: skia.GrProtected = <GrProtected.kNo: 0>) -> skia.GrBackendTexture

  4. createCompressedBackendTexture(self: skia.GrContext, width: int, height: int, type: SkImage::CompressionType, data: buffer, mipMapped: skia.GrMipmapped, isProtected: skia.GrProtected = <GrProtected.kNo: 0>) -> skia.GrBackendTexture

GrContext.defaultBackendFormat(self: skia.GrContext, colorType: SkColorType, renderable: skia.GrRenderable = <GrRenderable.kNo: 0>) skia.GrBackendFormat

Retrieve the default GrBackendFormat for a given ColorType and renderability.

It is guaranteed that this backend format will be the one used by the following ColorType and SurfaceCharacterization-based createBackendTexture() methods.

The caller should check that the returned format is valid.

GrContext.deleteBackendTexture(self: skia.GrContext, texture: skia.GrBackendTexture) None
GrContext.flush(*args, **kwargs)

Overloaded function.

  1. flush(self: skia.GrContext, info: skia.GrFlushInfo) -> skia.GrSemaphoresSubmitted

    Call to ensure all drawing to the context has been flushed to underlying 3D API specific objects. A call to GrContext.submit() is always required to ensure work is actually sent to the gpu. Some specific API details:

    GL

    Commands are actually sent to the driver, but glFlush is never called. Thus some sync objects from the flush will not be valid until a submission occurs.

    Vulkan/Metal/D3D/Dawn

    Commands are recorded to the backend APIs corresponding command buffer or encoder objects. However, these objects are not sent to the gpu until a submission occurs.

    If the return is GrSemaphoresSubmitted::kYes, only initialized GrBackendSemaphores will be submitted to the gpu during the next submit call (it is possible Skia failed to create a subset of the semaphores). The client should not wait on these semaphores until after submit has been called, but must keep them alive until then. If a submit flag was passed in with the flush these valid semaphores can we waited on immediately. If this call returns GrSemaphoresSubmitted::kNo, the GPU backend will not submit any semaphores to be signaled on the GPU. Thus the client should not have the GPU wait on any of the semaphores passed in with the GrFlushInfo. Regardless of whether semaphores were submitted to the GPU or not, the client is still responsible for deleting any initialized semaphores.

    Regardleess of semaphore submission the context will still be flushed. It should be emphasized that a return value of GrSemaphoresSubmitted::kNo does not mean the flush did not happen. It simply means there were no semaphores submitted to the GPU. A caller should only take this as a failure if they passed in semaphores to be submitted.

  2. flush(self: skia.GrContext) -> None

GrContext.flushAndSubmit(self: skia.GrContext) None

Call to ensure all drawing to the context has been flushed and submitted to the underlying 3D API. This is equivalent to calling flush() with a default GrFlushInfo followed by submit().

GrContext.freeGpuResources(self: skia.GrContext) None

Frees GPU created by the context.

Can be called to reduce GPU memory pressure.

GrContext.getResourceCacheLimit(self: skia.GrContext) int

Return the current GPU resource cache limit in bytes.

GrContext.getResourceCachePurgeableBytes(self: skia.GrContext) int

Gets the number of bytes in the cache consumed by purgeable (e.g. unlocked) resources.

GrContext.getResourceCacheUsage(self: skia.GrContext, resourceCount: int = None, maxResourceBytes: int = None) None

Gets the current GPU resource cache usage.

Parameters
  • resourceCount (int) – If non-null, returns the number of resources that are held in the cache.

  • maxResourceBytes (int) – If non-null, returns the total number of bytes of video memory held in the cache.

GrContext.maxRenderTargetSize(self: skia.GrContext) int

Gets the maximum supported render target size.

GrContext.maxSurfaceSampleCountForColorType(self: skia.GrContext, colorType: SkColorType) int

Gets the maximum supported sample count for a color type.

1 is returned if only non-MSAA rendering is supported for the color type. 0 is returned if rendering to this color type is not supported at all.

GrContext.maxTextureSize(self: skia.GrContext) int

Gets the maximum supported texture size.

GrContext.oomed(self: skia.GrContext) bool

Checks if the underlying 3D API reported an out-of-memory error.

If this returns true it is reset and will return false until another out-of-memory error is reported by the 3D API. If the context is abandoned then this will report false.

Currently this is implemented for:

OpenGL [ES] - Note that client calls to glGetError() may swallow GL_OUT_OF_MEMORY errors and therefore hide the error from Skia. Also, it is not advised to use this in combination with enabling GrContextOptions::fSkipGLErrorChecks. That option may prevent GrContext from ever checking the GL context for OOM.

Vulkan - Reports true if VK_ERROR_OUT_OF_HOST_MEMORY or VK_ERROR_OUT_OF_DEVICE_MEMORY has occurred.

GrContext.performDeferredCleanup(self: skia.GrContext, msNotUsed: datetime.timedelta) None

Purge GPU resources that haven’t been used in the past ‘msNotUsed’ milliseconds or are otherwise marked for deletion, regardless of whether the context is under budget.

GrContext.precompileShader(self: skia.GrContext, key: skia.Data, data: skia.Data) bool
GrContext.purgeResourcesNotUsedInMs(self: skia.GrContext, msNotUsed: datetime.timedelta) None
GrContext.purgeUnlockedResources(*args, **kwargs)

Overloaded function.

  1. purgeUnlockedResources(self: skia.GrContext, maxBytesToPurge: int, preferScratchResources: bool) -> None

    Purge unlocked resources from the cache until the the provided byte count has been reached or we have purged all unlocked resources.

    The default policy is to purge in LRU order, but can be overridden to prefer purging scratch resources (in LRU order) prior to purging other resource types.

    maxBytesToPurge

    the desired number of bytes to be purged.

    preferScratchResources

    If true scratch resources will be purged prior to other resource types.

  2. purgeUnlockedResources(self: skia.GrContext, scratchResourcesOnly: bool) -> None

    This entry point is intended for instances where an app has been backgrounded or suspended.

    If ‘scratchResourcesOnly’ is true all unlocked scratch resources will be purged but the unlocked resources with persistent data will remain. If ‘scratchResourcesOnly’ is false then all unlocked resources will be purged. In either case, after the unlocked resources are purged a separate pass will be made to ensure that resource usage is under budget (i.e., even if ‘scratchResourcesOnly’ is true some resources with persistent data may be purged to be under budget).

    scratchResourcesOnly

    If true only unlocked scratch resources will be purged prior enforcing the budget requirements.

GrContext.ref(self: skia.RefCntBase) None

Increment the reference count.

Must be balanced by a call to unref().

GrContext.releaseResourcesAndAbandonContext(self: skia.GrContext) None

This is similar to abandonContext() however the underlying 3D context is not yet lost and the GrContext will cleanup all allocated resources before returning.

After returning it will assume that the underlying context may no longer be valid.

The typical use case for this function is that the client is going to destroy the 3D context but can’t guarantee that GrContext will be destroyed first (perhaps because it may be ref’ed elsewhere by either the client or Skia objects).

For Vulkan, even if the device becomes lost, the VkQueue, VkDevice, or VkInstance used to create the GrContext must be alive before calling releaseResourcesAndAbandonContext().

GrContext.resetContext(self: skia.GrContext, state: int = 4294967295) None

The GrContext normally assumes that no outsider is setting state within the underlying 3D API’s context/device/whatever.

This call informs the context that the state was modified and it should resend. Shouldn’t be called frequently for good performance. The flag bits, state, is dependent on which backend is used by the context, either GL or D3D (possible in future).

GrContext.resetGLTextureBindings(self: skia.GrContext) None

If the backend is kOpenGL, then all texture unit/target combinations for which the GrContext has modified the bound texture will have texture id 0 bound.

This does not flush the GrContext. Calling resetContext() does not change the set that will be bound to texture id 0 on the next call to resetGLTextureBindings(). After this is called all unit/target combinations are considered to have unmodified bindings until the GrContext subsequently modifies them (meaning if this is called twice in a row with no intervening GrContext usage then the second call is a no-op.)

GrContext.setBackendRenderTargetState(self: skia.GrContext, target: skia.GrBackendRenderTarget, mutableState: skia.GrBackendSurfaceMutableState, previousState: skia.GrBackendSurfaceMutableState = None) bool
GrContext.setBackendTextureState(self: skia.GrContext, texture: skia.GrBackendTexture, mutableState: skia.GrBackendSurfaceMutableState, previousState: skia.GrBackendSurfaceMutableState = None) bool

Updates the state of the GrBackendTexture/RenderTarget to have the passed in GrBackendSurfaceMutableState.

All objects that wrap the backend surface (i.e. Surface and Image) will also be aware of this state change. This call does not submit the state change to the gpu, but requires the client to call GrContext.submit() to send it to the GPU. The work for this call is ordered linearly with all other calls that require GrContext.submit() to be called (e.g updateBackendTexture() and flush()).

See GrBackendSurfaceMutableState to see what state can be set via this call.

If the backend API is Vulkan, the caller can set the GrBackendSurfaceMutableState’s VkImageLayout to VK_IMAGE_LAYOUT_UNDEFINED or queueFamilyIndex to VK_QUEUE_FAMILY_IGNORED to tell Skia to not change those respective states.

If previousState is not null and this returns true, then Skia will have filled in previousState to have the values of the state before this call.

GrContext.setResourceCacheLimit(self: skia.GrContext, maxResourceBytes: int) None

Specify the GPU resource cache limit.

If the cache currently exceeds this limit, it will be purged (LRU) to keep the cache within the limit.

Parameters

maxResourceBytes – The maximum number of bytes of video memory that can be held in the cache.

GrContext.storeVkPipelineCacheData(self: skia.GrContext) None
GrContext.submit(self: skia.GrContext, syncCpu: bool = False) bool

Submit outstanding work to the gpu from all previously un-submitted flushes. The return value of the submit will indicate whether or not the submission to the GPU was successful.

If the call returns true, all previously passed in semaphores in flush calls will have been submitted to the GPU and they can safely be waited on. The caller should wait on those semaphores or perform some other global synchronization before deleting the semaphores.

If it returns false, then those same semaphores will not have been submitted and we will not try to submit them again. The caller is free to delete the semaphores at any time.

If the syncCpu flag is true this function will return once the gpu has finished with all submitted work.

GrContext.supportsDistanceFieldText(self: skia.GrContext) bool
GrContext.threadSafeProxy(self: skia.GrContext_Base) GrContextThreadSafeProxy
GrContext.unique(self: skia.RefCntBase) bool

May return true if the caller is the only owner.

Ensures that all previous owner’s actions are complete.

GrContext.unref(self: skia.RefCntBase) None

Decrement the reference count.

If the reference count is 1 before the decrement, then delete the object. Note that if this is the case, then the object needs to have been allocated via new, and not on the stack.

GrContext.updateBackendTexture(*args, **kwargs)

Overloaded function.

  1. updateBackendTexture(self: skia.GrContext, backendTexture: skia.GrBackendTexture, color: skia.Color4f) -> bool

    If possible, updates a backend texture to be filled to a particular color.

    The client should check the return value to see if the update was successful. The client can pass in a finishedProc to be notified when the data has been uploaded by the gpu and the texture can be deleted. The client is required to call GrContext.submit() to send the upload work to the gpu. The finishedProc will always get called even if we failed to update the GrBackendTexture. For the Vulkan backend after a successful update the layout of the created VkImage will be: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  2. updateBackendTexture(self: skia.GrContext, backendTexture: skia.GrBackendTexture, srcData: List[SkPixmap]) -> bool

    If possible, updates a backend texture to be filled to a particular color.

    The client should check the return value to see if the update was successful. The client can pass in a finishedProc to be notified when the data has been uploaded by the gpu and the texture can be deleted. The client is required to call GrContext.submit() to send the upload work to the gpu. The finishedProc will always get called even if we failed to update the GrBackendTexture. The backend texture must be compatible with the provided pixmap(s). Compatible, in this case, means that the backend format is compatible with the base pixmap’s colortype. The src data can be deleted when this call returns. If the backend texture is mip mapped, the data for all the mipmap levels must be provided. In the mipmapped case all the colortypes of the provided pixmaps must be the same. Additionally, all the miplevels must be sized correctly (please see SkMipmap::ComputeLevelSize and ComputeLevelCount). Note: the pixmap’s alphatypes and colorspaces are ignored. For the Vulkan backend after a successful update the layout of the created VkImage will be: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

GrContext.wait(self: skia.GrContext, semaphores: List[skia.GrBackendSemaphore], deleteSemaphoresAfterWait: bool = True) bool

Inserts a list of GPU semaphores that the current GPU-backed API must wait on before executing any more commands on the GPU.

Skia will take ownership of the underlying semaphores and delete them once they have been signaled and waited on. If this call returns false, then the GPU back-end will not wait on any passed in semaphores, and the client will still own the semaphores.