home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / povray / Docs / texture < prev    next >
Text File  |  1991-09-17  |  6KB  |  214 lines
  1.  
  2.   Persistence of Vision Raytracer
  3.   Adding new textures tutorial.
  4.   -----------------------------------
  5.  
  6.  The textures that modify the color, transparency and surface normal of an 
  7. object are a very powerful and effective feature of the the PV-Ray
  8. raytracer. They are the best and easiest way to achieve many visual effects.
  9.  
  10.  The following text is a short and simple tutorial on how to add new 
  11. textures to PV-Ray. If you would like to experiment with 
  12. new textures without going to all this trouble I have added several new
  13. "fill-in-the-blank" textures in the file TXTTEST.C. The work described here
  14. has already been done for six new textures (PAINTED1, 2 & 3 BUMPY1, 2 & 3)
  15. so you can try out new texture ideas without having to modify and recompile
  16. the entire program.
  17.  
  18.  The examples that follow describe how to add two new textures, NEW_COLOUR and
  19. NEW_BUMP. Several source files must be modified to add new textures to 
  20. PV-Ray.
  21.  
  22. -----POVPROTO.H
  23.  
  24.  POVPROTO.H contains all the function prototypes for STAR-Light. The first
  25. step to creating a new texture is to add a function prototype for your
  26. texture. It should be in the txttest.c section and in the form,
  27.  
  28. void new_colour PARAMS((DBL x, DBL y, DBL z, TEXTURE *Texture, COLOUR *Colour));
  29.   or
  30. void new_bump PARAMS((DBL x, DBL y, DBL z, TEXTURE *Texture, VECTOR *normal)); 
  31.  
  32. depending on whether your function will modify the colour or the surface
  33. normal.
  34.  
  35. -----FRAME.H 
  36.  
  37.  In frame.h the texture must be added to either the coloured texture
  38. list or the perturb normal (bumpy) texture list in the form,
  39.  
  40. /* Coloured texture list */
  41. #define NO_TEXTURE               0
  42. #define COLOUR_TEXTURE           1
  43. #define BOZO_TEXTURE             2
  44. #define MARBLE_TEXTURE           3
  45. ...(list of textures)
  46. #define NEW_COLOUR_TEXTURE       13    (last texture+1)    <----         
  47.  
  48.  
  49. /* Perturb normal (bumpy) texture list  */
  50. #define NO_BUMPS   0
  51. #define WAVES      1
  52. #define RIPPLES    2
  53. #define WRINKLES   3
  54. #define BUMPS      4              
  55. ...(list of textures)
  56. #define NEW_BUMP   13 (last texture+1)  <-----
  57.  
  58.  
  59. The texture also needs a token definition for the parser. Add that 
  60. like this,
  61.  
  62. /* Token Definitions for Parser */
  63.  
  64. #define AGATE_TOKEN                  0
  65. #define ALL_TOKEN                    1
  66. #define ALPHA_TOKEN                  2
  67. #define AMBIENT_TOKEN                3
  68. #define AMPERSAND_TOKEN              4
  69. #define AT_TOKEN                     5
  70. ...(token list)
  71. #define BUMPY3_TOKEN               137
  72. #define BUMPMAP_TOKEN              138
  73. #define BUMPSIZE_TOKEN             139
  74. #define NEW_COLOUR_TOKEN           140 <-----
  75. #define NEW_BUMP_TOKEN             141 <-----
  76. #define LAST_TOKEN                 142 <----- LAST_TOKEN must be last number
  77.  
  78.  
  79. -----TOKENIZE.C
  80.  
  81. Add your new keywords to the Reserved_Words structure in Tokenize.c in
  82. correct alphabetical order.  
  83.  
  84. struct Reserved_Word_Struct Reserved_Words [LAST_TOKEN] = {
  85.     AGATE_TOKEN, "AGATE",
  86.     ALL_TOKEN, "ALL",
  87.     ALPHA_TOKEN, "ALPHA",
  88.     ...(long list of tokens)
  89.     LOOK_AT_TOKEN, "LOOK_AT",
  90.     MARBLE_TOKEN, "MARBLE",
  91.     METALLIC_TOKEN, "METALLIC",
  92.     NEW_BUMP_TOKEN, "NEW_BUMP",     <-----
  93.         NEW_COLOUR_TOKEN, "NEW_COLOUR", <-----
  94.         OBJECT_TOKEN, "OBJECT", 
  95.     ...
  96.         WOOD_TOKEN, "WOOD",
  97.     WRINKLES_TOKEN, "WRINKLES"
  98.     };
  99.  
  100. -----PARSE.C
  101.  
  102.   In parse.c the routine Parse_Texture() must be changed for your new texture.
  103. The simplest way is to copy and modify an exsisting texture parse block. For
  104. example the granite texture parsing,
  105.  
  106.     CASE (GRANITE_TOKEN)
  107.     if (Texture->Constant_Flag) {
  108.         Texture = Copy_Texture (Texture);
  109.         Texture->Constant_Flag = FALSE;
  110.     }
  111. Texture -> Texture_Number = GRANITE_TEXTURE;
  112. END_CASE
  113.  
  114. , becomes new colour texture parsing by changing two lines
  115.  
  116. CASE (NEW_COLOUR_TOKEN) <-----
  117. if (Texture->Constant_Flag) {
  118.     Texture = Copy_Texture (Texture);
  119.     Texture->Constant_Flag = FALSE;
  120. }
  121. Texture -> Texture_Number = NEW_COLOUR_TEXTURE; <-----
  122. END_CASE
  123.  
  124. The syntax for NEW_COLOUR will be identical to granite and other textures
  125. like marble, agate, etc.
  126.  
  127. New_bump is parsed the almost the same way, but the bumpy textures
  128. parse a mandatory Bump_Amount value directly after the texture keyword...
  129.  
  130. CASE (RIPPLES_TOKEN)
  131. if (Texture->Constant_Flag) {
  132.     Texture = Copy_Texture (Texture);
  133.     Texture->Constant_Flag = FALSE;
  134. }
  135. Texture -> Bump_Number = RIPPLES;
  136. Texture -> Bump_Amount = Parse_Float ();
  137. END_CASE
  138.  
  139. CASE (NEW_BUMP_TOKEN) <-----
  140. if (Texture->Constant_Flag) {
  141.     Texture = Copy_Texture (Texture);
  142.     Texture->Constant_Flag = FALSE;
  143. }
  144. Texture -> Bump_Number = NEW_BUMP; <-------
  145. Texture -> Bump_Amount = Parse_Float ();
  146. END_CASE
  147.  
  148. The syntax for NEW_BUMP will be identical to ripples and other textures
  149. such as bumps, dents, wrinkles, etc.
  150.  
  151. -----LIGHTING.C
  152.  
  153. Lighting.c is where your new texture is called from. Your texture has to
  154. be added to the Colour_At() or the Perturb_Normal() function. Each of these
  155. have a switch statement that calls the correct texture,
  156.  
  157. ---Colour_At():
  158.  
  159. switch (Texture->Texture_Number) {
  160. case NO_TEXTURE:
  161.     /* No colouring texture has been specified - make it black. */
  162.     Make_Colour (Colour, 0.0, 0.0, 0.0);
  163.     Colour -> Alpha  = 0.0;
  164.     break;
  165.  
  166. case BOZO_TEXTURE: 
  167.     Bozo (x, y, z, Texture, Colour);
  168.     break;
  169.  
  170. case MARBLE_TEXTURE:
  171.     marble (x, y, z, Texture, Colour);
  172.     break;    
  173.  
  174. case NEW_COLOUR_TEXTURE:                 <-----
  175.     new_colour (x, y, z, Texture, Colour); <-----
  176.     break;                                 <-----
  177. }      
  178.  
  179. ---Perturb_Normal():
  180.  
  181. switch (Texture->Bump_Number) {
  182. case NO_BUMPS: 
  183.     break;
  184.  
  185. case WAVES: 
  186.     waves (x, y, z, Texture, New_Normal);
  187.     break;
  188.  
  189. case RIPPLES: 
  190.     ripples (x, y, z, Texture, New_Normal);
  191.     break;
  192.  
  193. case NEW_BUMP: 
  194.     new_bump (x, y, z, Texture, New_Normal);  <-----
  195.       break;                                    <-----
  196.  
  197. }
  198.  
  199. Now everything is set up to add the actual routines NEW_COLOUR and NEW_BUMP
  200. to txttest.c or a new file.
  201.  
  202. -----TXTTEST.C (or MYTXT.C or whatever)
  203.  
  204.  Everything up to this point has been preparing the raytracer to
  205. recognize your new texture keywords in the scene description file, store 
  206. a description of that texture for later retrieval and call the texture
  207. code at the correct time. With all that work done the only thing left is
  208. to write the routine that actually modifies the surface color or perturbs
  209. the surface normal. The best way to learn how to do this is to study the
  210. code in txtcolor.c and txtbump.c. 
  211.  
  212. Good luck & have fun!
  213.    Drew Wells
  214.