Document the lifetime or ownership of resources and validated textures.

1 files 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);