From 48ac976821c5fe5a815c5c756b97ff4b702c3ced Mon Sep 17 00:00:00 2001
From: David Rose <david@ddrose.com>
Date: Mon, 13 Jan 2003 16:16:20 +0000
Subject: [PATCH] update comment

---
 panda/src/gobj/texture.I   | 21 +++++++++++++++++++++
 panda/src/gobj/texture.cxx | 14 +++++++++++---
 2 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/panda/src/gobj/texture.I b/panda/src/gobj/texture.I
index 2eec072de6..a976e4419f 100644
--- a/panda/src/gobj/texture.I
+++ b/panda/src/gobj/texture.I
@@ -90,6 +90,27 @@ uses_mipmaps() const {
 //  Description: Returns true if the Texture has its image contents
 //               available in main RAM, false if it exists only in
 //               texture memory or in the prepared GSG context.
+
+//               Note that this has nothing to do with whether
+//               get_ram_image() will fail or not.  Even if
+//               has_ram_image() returns false, get_ram_image() may
+//               still return a valid RAM image, because
+//               get_ram_image() will automatically load the texture
+//               from disk if necessary.  The only thing
+//               has_ram_image() tells you is whether the texture is
+//               available right now without hitting the disk first.
+//
+//               Note also that if an application uses only one GSG,
+//               it may appear that has_ram_image() returns true if
+//               the texture has not yet been loaded by the GSG, but
+//               this correlation is not true in general and should
+//               not be depended on.  Specifically, if an application
+//               ever uses multiple GSG's in its lifetime (for
+//               instance, by opening more than one window, or by
+//               closing its window and opening another one later),
+//               then has_ram_image() may well return false on
+//               textures that have never been loaded on the current
+//               GSG.
 ////////////////////////////////////////////////////////////////////
 INLINE bool Texture::
 has_ram_image() const {
diff --git a/panda/src/gobj/texture.cxx b/panda/src/gobj/texture.cxx
index 72769df7ed..85a45b1951 100644
--- a/panda/src/gobj/texture.cxx
+++ b/panda/src/gobj/texture.cxx
@@ -503,9 +503,17 @@ clear_gsg(GraphicsStateGuardianBase *gsg) {
 //               false, and we have previously prepared this texture
 //               with a GSG.
 //
-//               It is possible that the RAM image is still
-//               unavailable.  If that happens, this function returns
-//               NULL.
+//               Note that it is not correct to call has_ram_image()
+//               first to test whether this function will fail.  A
+//               false return value from has_ram_image() indicates
+//               only that get_ram_image() may need to reload the
+//               texture from disk, which it will do automatically.
+//
+//               On the other hand, it is possible that the texture
+//               cannot be found on disk or is otherwise unavailable.
+//               If that happens, this function returns NULL.  There
+//               is no way to predict whether get_ram_image() will
+//               return NULL without calling it first.
 ////////////////////////////////////////////////////////////////////
 PixelBuffer *Texture::
 get_ram_image() {