From 45905bad283f6f833b574f2a74adf095744a53fd Mon Sep 17 00:00:00 2001 From: Chia-I Wu Date: Mon, 25 Jan 2010 14:57:11 +0800 Subject: Document the lifetime or ownership of resources and validated textures. --- st_api.h | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/st_api.h b/st_api.h index 2b1e9aa..5e9f7d2 100644 --- a/st_api.h +++ b/st_api.h @@ -177,6 +177,12 @@ struct st_framebuffer * * The implementor of this function needs to also ensure * thread safty as this call might be done from multiple threads. + * + * The returned textures are owned by the caller. They should be + * unreferenced when no longer used. If this function is called multiple + * times with different sets of attachments, those buffers not included in + * the last call might be destroyed. This behavior might change in the + * future. */ boolean (*validate)(struct st_framebuffer *stfb, const enum st_framebuffer_attachment *statts, @@ -200,7 +206,9 @@ struct st_context * Lock and unlock a state tracker context resource. * * This gives access to the underlying data structure of a state tracker - * context resource. + * context resource. Unless there is some mechanism not defined here that + * can lengthen the lifetime of the data structure, it is valid only until + * unlocked. */ void *(*lock_resource)(struct st_context *stctx, enum st_context_resource_type type, void *res); @@ -273,7 +281,9 @@ struct st_manager * Lock and unlock a state tracker manager resource. * * This gives access to the underlying data structure of a state tracker - * manager resource. + * manager resource. Unless there is some mechanism not defined here that + * can lengthen the lifetime of the data structure, it is valid only until + * unlocked. */ void *(*lock_resource)(struct st_manager *smapi, enum st_manager_resource_type type, void *res); -- cgit v1.2.3