polish and document new image drawing functions

Graphics/drawContext.cpp

@@ -18,6 +18,7 @@
 #include "PViewOptions.h"
 #include "VertexArray.h"
 #include "StringUtils.h"
+#include "OS.h"
 #include "gl2ps.h"
 
 #if defined(HAVE_FLTK)
@@ -381,6 +382,11 @@ bool drawContext::generateTextureForImage(const std::string &name, int page,
                                           GLuint &imageTexture, GLuint &imageW,
                                           GLuint &imageH)
 {
+  if(StatFile(name)){
+    Msg::Warning("Could not open file `%s'", name.c_str());
+    return false;
+  }
+
   std::string ext = SplitFileName(name)[2];
   if(ext == ".pdf" || ext == ".PDF"){
 #if defined(HAVE_POPPLER)

Graphics/drawGlyph.cpp

@@ -137,15 +137,15 @@ void drawContext::drawImage(const std::string &name, double x, double y, double
 {
   // format can be "@wxh" or "@wxh,wx,wy,wz,hx,hy,hz", where w and h are the
   // width and height (in model coordinates for T3 or in pixels for T2) of the
-  // image, wx,wy,wz is direction of the bottom edge of the image and hx,hy,hz
-  // is the direction of the left edge of the image.
+  // image, wx,wy,wz is the direction of the bottom edge of the image and
+  // hx,hy,hz is the direction of the left edge of the image.
   size_t p = name.find_last_of("@");
   std::string file = name, format;
   if(p != std::string::npos){
     format = name.substr(p + 1);
     file = name.substr(0, p);
   }
-  double w = 0., h = 0., wx = 1., wy = 0., wz = 0., hx = 0., hy = 0., hz = 0.;
+  double w = 0., h = 0., wx = 1., wy = 0., wz = 0., hx = 0., hy = 1., hz = 0.;
   if(format.size()){
     bool ok;
     if(format.find(",") != std::string::npos)

doc/texinfo/gmsh.texi

@@ -1141,9 +1141,10 @@ Character expressions are defined as:
 @end example
 
 @code{Today} returns the current date. @code{OnelabAction} returns the
-current ONELAB action. @code{GmshExecutableName} returns the full path
-of the Gmsh executable.  @code{CurrentDirectory} and @code{CurrentDir}
-return the directory of the @code{.geo} file.  @code{StrPrefix} and
+current ONELAB action (e.g. @code{check} or
+@code{compute}). @code{GmshExecutableName} returns the full path of the
+Gmsh executable.  @code{CurrentDirectory} and @code{CurrentDir} return
+the directory of the @code{.geo} file.  @code{StrPrefix} and
 @code{StrRelative} permit to take the prefix (e.g. to remove the
 extension) or the relative path of a file name. @code{StrCat} and
 @code{Str} permit to concatenate character expressions (@code{Str} adds
@@ -3318,7 +3319,15 @@ world) coordinates.  The fourth @var{expression} has the same meaning as the
 third @var{expression} in 2D text objects.
 
 For both 2D and 3D text objects, the @var{list-of-values} can contain an
-arbitrary number of @w{@var{char-expression}s}.
+arbitrary number of @w{@var{char-expression}s}. If the
+@var{char-expression} starts with @code{file://}, the remainder of the
+string is interpreted as the name of an image file, and the image is
+displayed instead of the string. A format string in the form
+@code{@@wxh} or @code{@@wxh,wx,wy,wz,hx,hy,hz}, where @code{w} and
+@code{h} are the width and height (in model coordinates for @code{T3} or
+in pixels for @code{T2}) of the image, @code{wx,wy,wz} is the direction
+of the bottom edge of the image and @code{hx,hy,hz} is the direction of
+the left edge of the image.
 
 The optional @code{TIME} list can contain a list of expressions giving the
 value of the time (or any other variable) for which an evolution was saved.