GrContext

GrContext: alias of GrDirectContext

Methods

static GrContext.ComputeImageSize(image: SkImage, mipMapped: skia.GrMipmapped, useNextPow2: bool = False) → int

static GrContext.MakeGL(*args, **kwargs)

Overloaded function.

MakeGL(interface: GrGLInterface, options: skia.GrContextOptions) -> skia.GrDirectContext

Creates a GrDirectContext for a backend context. If no GrGLInterface is provided then the result of GrGLMakeNativeInterface() is used if it succeeds.
MakeGL(interface: GrGLInterface) -> skia.GrDirectContext
MakeGL(options: skia.GrContextOptions) -> skia.GrDirectContext
MakeGL() -> skia.GrDirectContext

static GrContext.MakeMock(*args, **kwargs)

Overloaded function.

MakeMock(mockOptions: GrMockOptions, options: skia.GrContextOptions) -> skia.GrDirectContext
MakeMock(mockOptions: GrMockOptions) -> skia.GrDirectContext

static GrContext.MakeVulkan(*args, **kwargs)

Overloaded function.

MakeVulkan(backendContext: skgpu::VulkanBackendContext, options: skia.GrContextOptions) -> skia.GrDirectContext

The Vulkan context (VkQueue, VkDevice, VkInstance) must be kept alive until the returned GrDirectContext is destroyed. This also means that any objects created with this GrDirectContext (e.g. Surfaces, Images, etc.) must also be released as they may hold refs on the GrDirectContext. Once all these objects and the GrDirectContext are released, then it is safe to delete the vulkan objects.
MakeVulkan(backendContext: skgpu::VulkanBackendContext) -> skia.GrDirectContext

GrContext.__init__(*args, **kwargs)

GrContext.abandonContext(*args, **kwargs)

Overloaded function.

abandonContext(self: skia.GrDirectContext) -> 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.
abandonContext(self: skia.GrDirectContext) -> 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.GrDirectContext) → 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.GrDirectContext) → None: Checks whether any asynchronous work is complete and if so calls related callbacks.

GrContext.colorTypeSupportedAsImage(self: skia.GrDirectContext, colorType: SkColorType) → bool: Can a Image be created with the given color type.

GrContext.colorTypeSupportedAsSurface(self: skia.GrDirectContext, 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.GrDirectContext, compressionType: SkTextureCompressionType) → 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.

createBackendTexture(self: skia.GrDirectContext, width: int, height: int, backendFormat: skia.GrBackendFormat, mipMapped: skia.GrMipmapped, renderable: skia.GrRenderable, isProtected: skia.GrProtected = skia.GrProtected.kNo, label: str = ‘’) -> 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.
createBackendTexture(self: skia.GrDirectContext, width: int, height: int, colorType: SkColorType, mipMapped: skia.GrMipmapped, renderable: skia.GrRenderable, isProtected: skia.GrProtected = skia.GrProtected.kNo, label: str = ‘’) -> 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.
createBackendTexture(self: skia.GrDirectContext, width: int, height: int, backendFormat: skia.GrBackendFormat, color: skia.Color4f, mipMapped: skia.GrMipmapped, renderable: skia.GrRenderable, isProtected: skia.GrProtected = skia.GrProtected.kNo) -> 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 GrDirectContext::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
createBackendTexture(self: skia.GrDirectContext, width: int, height: int, colorType: SkColorType, color: skia.Color4f, mipMapped: skia.GrMipmapped, renderable: skia.GrRenderable, isProtected: skia.GrProtected = skia.GrProtected.kNo) -> 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
createBackendTexture(self: skia.GrDirectContext, srcData: list[SkPixmap], renderable: skia.GrRenderable, isProtected: skia.GrProtected = skia.GrProtected.kNo) -> 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 GrDirectContext::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
createBackendTexture(self: skia.GrDirectContext, pixmap: SkPixmap, renderable: skia.GrRenderable, isProtected: skia.GrProtected = skia.GrProtected.kNo) -> skia.GrBackendTexture

GrContext.createCompressedBackendTexture(*args, **kwargs)

Overloaded function.

createCompressedBackendTexture(self: skia.GrDirectContext, width: int, height: int, backendFormat: skia.GrBackendFormat, color: skia.Color4f, mipMapped: skia.GrMipmapped, isProtected: skia.GrProtected = skia.GrProtected.kNo) -> 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
createCompressedBackendTexture(self: skia.GrDirectContext, width: int, height: int, type: SkTextureCompressionType, color: skia.Color4f, mipMapped: skia.GrMipmapped, isProtected: skia.GrProtected = skia.GrProtected.kNo) -> skia.GrBackendTexture
createCompressedBackendTexture(self: skia.GrDirectContext, width: int, height: int, backendFormat: skia.GrBackendFormat, data: Buffer, mipMapped: skia.GrMipmapped, isProtected: skia.GrProtected = skia.GrProtected.kNo) -> skia.GrBackendTexture
createCompressedBackendTexture(self: skia.GrDirectContext, width: int, height: int, type: SkTextureCompressionType, data: Buffer, mipMapped: skia.GrMipmapped, isProtected: skia.GrProtected = skia.GrProtected.kNo) -> skia.GrBackendTexture

GrContext.defaultBackendFormat(self: skia.GrDirectContext, colorType: SkColorType, renderable: skia.GrRenderable = skia.GrRenderable.kNo) → 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.GrDirectContext, texture: skia.GrBackendTexture) → None

GrContext.flush(*args, **kwargs)

Overloaded function.

flush(self: skia.GrDirectContext, 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.
flush(self: skia.GrDirectContext) -> None

GrContext.flushAndSubmit(self: skia.GrDirectContext, sync: skia.GrSyncCpu = skia.GrSyncCpu.kNo) → 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(*args, **kwargs)

Overloaded function.

freeGpuResources(self: skia.GrDirectContext) -> None

Frees GPU created by the context.

Can be called to reduce GPU memory pressure.
freeGpuResources(self: skia.GrDirectContext) -> None

Frees GPU created by the context.

Can be called to reduce GPU memory pressure.

GrContext.getResourceCacheLimit(self: skia.GrDirectContext) → int: Return the current GPU resource cache limit in bytes.

GrContext.getResourceCachePurgeableBytes(self: skia.GrDirectContext) → int: Gets the number of bytes in the cache consumed by purgeable (e.g. unlocked) resources.

GrContext.getResourceCacheUsage(self: skia.GrDirectContext, 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.GrDirectContext) → int: Gets the maximum supported render target size.

GrContext.maxSurfaceSampleCountForColorType(self: skia.GrDirectContext, 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.GrDirectContext) → int: Gets the maximum supported texture size.

GrContext.oomed(self: skia.GrDirectContext) → 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.precompileShader(self: skia.GrDirectContext, key: skia.Data, data: skia.Data) → bool

GrContext.purgeResourcesNotUsedInMs(self: skia.GrDirectContext, msNotUsed: datetime.timedelta) → None

GrContext.purgeUnlockedResources(*args, **kwargs)

Overloaded function.

purgeUnlockedResources(self: skia.GrDirectContext, 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.
purgeUnlockedResources(self: skia.GrDirectContext, opts: skia.GrPurgeResourceOptions) -> None

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

opts:

If kScratchResourcesOnly 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(*args, **kwargs)

Overloaded function.

releaseResourcesAndAbandonContext(self: skia.GrDirectContext) -> 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().
releaseResourcesAndAbandonContext(self: skia.GrDirectContext) -> 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.GrDirectContext, 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.GrDirectContext) → 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.GrDirectContext, target: skia.GrBackendRenderTarget, mutableState: skgpu::MutableTextureState, previousState: skgpu::MutableTextureState = None) → bool

GrContext.setBackendTextureState(self: skia.GrDirectContext, texture: skia.GrBackendTexture, mutableState: skgpu::MutableTextureState, previousState: skgpu::MutableTextureState = 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.GrDirectContext, 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.GrDirectContext) → None

GrContext.submit(self: skia.GrDirectContext, sync: skia.GrSyncCpu = skia.GrSyncCpu.kNo) → 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.GrDirectContext) → 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.

updateBackendTexture(self: skia.GrDirectContext, 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
updateBackendTexture(self: skia.GrDirectContext, 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.GrDirectContext, 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.