home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / misc / volume21 / sipp / part07 < prev    next >
Text File  |  1991-07-23  |  50KB  |  1,615 lines
  1. Newsgroups: comp.sources.misc
  2. From: Jonas Yngvesson <jonas-y@isy.liu.se>
  3. Subject:  v21i032:  sipp - A 3D rendering library v2.1, Part07/08
  4. Message-ID: <1991Jul23.181801.28000@sparky.IMD.Sterling.COM>
  5. X-Md4-Signature: db212cb96d3ef57e8b2fec27ce5c0a5d
  6. Date: Tue, 23 Jul 1991 18:18:01 GMT
  7. Approved: kent@sparky.imd.sterling.com
  8.  
  9. Submitted-by: Jonas Yngvesson <jonas-y@isy.liu.se>
  10. Posting-number: Volume 21, Issue 32
  11. Archive-name: sipp/part07
  12. Supersedes: sipp2.0: Volume 16, Issue 5-10
  13. Environment: UNIX
  14.  
  15. #!/bin/sh
  16. # This is part 07 of sipp-2.1
  17. # ============= doc/sipp.man ==============
  18. if test ! -d 'doc'; then
  19.     echo 'x - creating directory doc'
  20.     mkdir 'doc'
  21. fi
  22. if test -f 'doc/sipp.man' -a X"$1" != X"-c"; then
  23.     echo 'x - skipping doc/sipp.man (File already exists)'
  24. else
  25. echo 'x - extracting doc/sipp.man (Text)'
  26. sed 's/^X//' << 'SHAR_EOF' > 'doc/sipp.man' &&
  27. .\" Copyright Jonas Yngvesson, Inge Wallin
  28. .\" This program and documentation may be distributed freely under
  29. .\" the terms of GNU GENERAL PUBLIC LICENSE.
  30. .TH SIPP 3X "July , 1991" 3X
  31. .SH NAME
  32. sipp - simple polygon processor, a 3d-graphics library
  33. .SH SYNOPSIS
  34. \fI#include <sipp.h>\fR
  35. .sp
  36. [g]cc [\fIflags\fR] \fIfiles\fR -lsipp -lm [ \fIlibraries\fR ]
  37. X
  38. .SH DESCRIPTION
  39. \fIsipp\fR is a library for creating 3-dimensional scenes and
  40. rendering them using a scan-line z-buffer algorithm. A scene is built
  41. up of objects which can be transformed with rotation, translation and
  42. scaling. The objects form hierarchies where each object can have
  43. arbitrarily many subobjects and subsurfaces. A surface is a number of
  44. connected polygons which are rendered using either Phong, Gouraud or
  45. Flat shading. An image can also be rendered as a line drawing of the
  46. polygon edges without any shading at all.
  47. .sp
  48. The library has an internal database for the objects to be rendered.
  49. Objects can be installed in, and removed from, this database at any
  50. time.
  51. .sp
  52. The library also provides support for texture mapping with
  53. automatic interpolation of texture coordinates. Simple anti-aliasing can be
  54. performed with oversampling. A scene can be illuminated by an arbitrary number
  55. of light sources. A basic shading algorithm is provided with the library, but
  56. the user can also use his own shading algorithms for each surface.
  57. .sp
  58. Images can be rendered directly onto a file in the Portable Pixmap
  59. format (ppm) (or, for line images, Portable Bitmap, pbm) or into a
  60. pixmap (bitmap) in core. The representation of the pixmap is not
  61. restricted in any way.
  62. X
  63. .SH USAGE
  64. Before any other function in \fIsipp\fR is used, the function
  65. \fIsipp_init()\fR must always be called. This call initiates the
  66. internal database and other global variables. The rest of this section
  67. describes the ideas behind \fIsipp\fR and outlines its usage. See the
  68. section 
  69. .B FUNCTIONS
  70. for details.
  71. .sp
  72. All objects in \fIsipp\fR are built up of \fIpolygons\fR with 3 or
  73. more \fIvertices\fR. The polygons can either be concave or convex, but
  74. all vertices must lie in the same plane. No test is done to assertain
  75. this, however. A number of polygons can form a, possibly non-planar,
  76. \fIsurface\fR. Inside a surface, a surface normal is stored with each
  77. vertex. This normal is the average of the normals of the polygons
  78. surrounding the vertex.
  79. .sp
  80. Surfaces are grouped together into objects which can also
  81. have other objects as subobjects. Each object or subobject can be
  82. transformed using the standard transformations: rotation, scaling and
  83. translation. All transformations are done with respect to the parent
  84. object if the object is a subobject, and the world if the object is a
  85. top level object.
  86. .sp
  87. When an object is defined, copies can be made of it and it can be
  88. installed into the internal database for rendering. The installation
  89. doesn't affect the object in any way, i.e. it can still be transformed
  90. and copied. This is useful if more pictures than one is to be created,
  91. e.g. in an animation.
  92. .sp
  93. \fIsipp\fR uses a number of stacks to create a scene. First,
  94. \fIvertices\fR of a polygon are pushed onto a \fIvertex stack\fR. When
  95. all vertices in a polygon are pushed, a \fIpolygon\fR is created from
  96. them and is pushed onto a \fIpolygon stack\fR. When a number of
  97. polygons have been pushed, a call to a function in \fIsipp\fR combine
  98. them into a \fIsurface\fR and returns a pointer to the surface. This
  99. surface can then be inserted into an \fIobject\fR together with other
  100. surfaces.  Objects can be transformed, used as subobjects in other
  101. objects and inserted into the scene database.
  102. .sp
  103. To create a polygon, two functions are used: \fIvertex_push()\fR and
  104. \fIpolygon_push()\fR. Variations of these functions exist, but these
  105. are the simple forms which are the easiest to use. A call to
  106. \fIvertex_push()\fR is done for each vertex in the polygons, going
  107. counter clockwise around the edge. The order in which the vertices are
  108. pushed is important, because this determines the front and the back
  109. face of the polygon. When all polygons are pushed onto the vertex
  110. stack, \fIpolygon_push()\fR is called. This call creates a polygon
  111. structure out of the pushed vertices, deletes them from the vertex
  112. stack, and pushes the newly created polygon onto the polygon stack.
  113. .sp
  114. When all polygons in a surface is on the polygon stack,
  115. \fIsurface_create()\fR (or one of it's variations) will create a
  116. surface out of them and empty the polygon stack for a new surface
  117. definition.  \fIsurface_create()\fR returns a pointer to the created
  118. surface.
  119. .sp
  120. An object is created with the function \fIobject_create()\fR. This
  121. function returns a pointer to an empty object, i.e. it contains no
  122. surfaces or subobjects. Surfaces and subobjects are added to an object
  123. with the functions \fIobject_add_surface()\fR and \fIobject_add
  124. subobj()\fR. When all surfaces and subobjects are added to the object
  125. it can be installed in the rendering database, or removed from it,
  126. with the functions \fIobject_install()\fR and \fIobject_uninstall()\fR
  127. respectively.
  128. .sp
  129. The finished database can be rendered in a number of different modes.
  130. \fIPHONG\fR rendering interpolates the surface normals over the polygons and
  131. call the shading function at each point (See the section \fBSHADING
  132. FUNCTIONS\fR for more details on them). This is the slowest method but it also
  133. produces the best result and is the only mode which can do texture mapping
  134. correctly. \fIGOURAUD\fR rendering calls the shading function only at the
  135. vertices and then interpolates the resulting color over the polygon.
  136. \fIFLAT\fR rendering calls the shading function only once per polygon and
  137. fills the polygon with the resulting color. \fILINE\fR rendering draws only
  138. the outlines of the polygons. This mode uses no color and is the fastest. No
  139. hidden line removal is done.
  140. X
  141. .SH DATA TYPES
  142. The \fIsipp\fR library defines a number of data types in the file
  143. \fIsipp.h\fR. These data types are:
  144. X
  145. .IP \fIbool\fR
  146. \fIbool\fR can be used as a boolean type, with values \fITRUE\fR of
  147. \fIFALSE\fR. These constants are also defined in \fIsipp.h\fR.
  148. X
  149. .IP \fIColor\fR
  150. \fIColor\fR is a struct with three members, \fIred\fR, \fIgrn\fR and
  151. \fIblu\fR.  Each member of the struct is a double which should be in
  152. the range [0,1].
  153. X
  154. .IP \fIVector\fR
  155. A \fIVector\fR is a struct with three members, \fIx\fR, \fIy\fR and
  156. \fIz\fR which are all doubles.
  157. X
  158. .IP \fITransf_mat\fR
  159. \fITransf_mat\fR is a standard 4 x 4 homogenous transformation matrix.
  160. Actually it is stored as a 4 x 3 matrix to save memory, since the
  161. rightmost column is only needed in the viewing calculation.
  162. .sp
  163. The members of a \fITransf_mat\fR should never be accessed directly, but
  164. rather through the abstract functions described in the \fBFUNCTIONS\fR
  165. section. 
  166. X
  167. .IP \fISurface\fR\ and\ \fIObject\fR
  168. \fISurface\fR and \fIObject\fR are both opaque types used by \fIsipp\fR. The
  169. actual definition of them is not important to the user.
  170. X
  171. .IP \fISurf_desc\fR
  172. A \fISurf_desc\fR is a surface description, used by the built-in shader to
  173. determine properties about a surface. The definition of \fISurf_desc\fR is as
  174. follows: 
  175. .br
  176. \fItypedef\ struct {\fR
  177. .br
  178. \fI    double\  ambient;\fR\       /* Fraction of color visible in ambient light */
  179. .br
  180. \fI    double\  specular;\fR\      /* Fraction of colour specularly reflected */
  181. .br
  182. \fI    double\  c3;\fR\            /* "Shininess" 0 = shiny,  1 = dull */
  183. .br
  184. \fI    Color\   color;\fR\         /* Colour of the surface */
  185. .br
  186. \fI}\ Surf_desc;\fR
  187. X
  188. .IP \fILightsource\fR
  189. All lightsources in the scene are kept in a linked list where the
  190. nodes are defined like this:
  191. .sp
  192. .I typedef struct lightsource {
  193. .br
  194. \fI\    double intensity;\fR
  195. .br
  196. \fI\    Vector dir;\fR
  197. .br
  198. \fI\    struct lightsource *next;\fR
  199. .br
  200. .I } Lightsource;
  201. .sp
  202. A pointer to the head of this list is sent to the shader.
  203. X
  204. .SH TEXTURE COORDINATES
  205. When defining a vertex of a polygon, up to 3 \fItexture coordinates\fR can be
  206. assigned to it. These coordinates are floating point numbers and the
  207. interpretation of them are up to the user. The texture coordinates are
  208. interpolated across the polygon when it is being rendered and these
  209. interpolated values are sent as parameters to the shading function. Since it
  210. is the shader that decides how the texture coordinates are to be used it is
  211. only the \fIPHONG\fR shading mode, which calls the shader in every point, that
  212. can do correct texture mapping.
  213. X
  214. .SH SHADING FUNCTIONS
  215. Each surface in a scene has a shading function associated with it.
  216. \fIsipp\fR has an internal basic shading function called
  217. \fIbasic_shader()\fR that can be used in most cases.
  218. \fIbasic_shader()\fR provides a somewhat modified and simplified
  219. version of Blinn's shading model, taking a \fISurf_desc\fR as a
  220. description of the surface.
  221. .sp
  222. If the user is not satisfied with the builtin shader, he can provide
  223. his own shader and surface description struct. All shaders take
  224. the same parameters and must be defined as follows:
  225. .sp
  226. \fIvoid\ myshader(nx,\ ny,\ nz,\ \ u,\ v,\ w,\ view_vec,\fR
  227. .br
  228. \fI        lights,\ surface,\ color)\fR
  229. .br
  230. \fI    double nx, ny, nz;\fR
  231. .br
  232. \fI    double u, v, w;\fR
  233. .br
  234. \fI    Vector\ view_vec;\fR
  235. .br
  236. \fI    Lightsource *lights;\fR
  237. .br
  238. \fI    void *surface;\fR
  239. .br
  240. \fI    Color\ *color;\fR
  241. .sp
  242. \fInx, ny\fR and \fInz\fR is the \fInon-normalized\fR surface normal at the
  243. point that should be rendered.
  244. .br
  245. \fIu, v\fR and \fIw\fR are the interpolated texture coordinates at the rendered
  246. point. If no texture coordinates have been given at some vertices these
  247. values are undefined and contains garbage at best.
  248. .br
  249. \fIview_vec\fR is a normalized vector, pointing from the rendered
  250. point at the viewpoint.
  251. .br
  252. \fIlights\fR is a pointer to a linked list of lightsource descriptions. See
  253. the function \fIlightsource_push()\fR for a description of the structure of
  254. the links.
  255. .br
  256. \fIsurface\fR is the same \fIsurface\fR-pointer that was sent to the
  257. function \fIsurface_create()\fR. In the case of \fIbasic_shader\fR this is
  258. a pointer to a \fISurf_desc\fR. If the user provides his own shader, he
  259. can also provide his own surface description.
  260. .br
  261. Upon return, the shader should place the calculated rgb colour
  262. components in the areas pointed to by \fIcolor\fR. The rgb components
  263. must be values between 0 and 1.
  264. X
  265. .SH FUNCTIONS
  266. X
  267. .IP \fIvoid\ sipp_init()\fR
  268. Initializes the whole library and emptys the internal database. This
  269. function must be called before any other function in the library.
  270. X
  271. .IP \fIvoid\ sipp_show_backfaces(flag)\fR
  272. .br
  273. \fIbool\ flag;\fR
  274. .sp
  275. This function can be used if backface culling should not be performed. If
  276. \fIflag\fR is \fITRUE\fR backfacing polygons are "inverted" (their surface
  277. normal is negated) and then rendered. This is useful if an object description
  278. does not use a consequent ordering of the vertices. Note, however, that the
  279. rendering step can be slowed down considerably since, on the average, twice as
  280. many polygons need to be rendered. The default (set by \fIsipp_init()\fR) is
  281. that backface culling should be performed.
  282. X
  283. .IP \fIvoid\ vertex_push(x,\ y,\ z)\fR
  284. .br
  285. \fIdouble\ x,\ y,\ z;\fR
  286. .sp
  287. Push a vertex onto the internal vertex stack.
  288. .br
  289. Note: Vertices must be pushed on the vertex stack
  290. \fIcounterclockwize\fR when looking at the "front" face of the
  291. polygon. Otherwize the front of the surface will be defined in the
  292. wrong direction.
  293. X
  294. .IP \fIvoid\ vertex_tx_push(x,\ y,\ z,\ u,\ v,\ w)\fR
  295. .br
  296. \fIdouble\ x,\ y,\ z;\fR
  297. .br
  298. \fIdouble\ u,\ v,\ w;\fR
  299. .sp
  300. Push a vertex and it's texture coordinates onto the vertex stack. Three texture
  301. coordinates are provided to make it possible to use both 2d and solid texture.
  302. The texture coordinates are interpolated between vertices on the same object
  303. and are \fInot\fR affected by transformations of the object. The interpolated
  304. coordinates will be sent to the shader. The coordinates can of course be used
  305. to hold any attribute that one whishes to interpolate between vertices and
  306. then use in the shader.
  307. X
  308. .IP \fIvoid\ polygon_push()\fR
  309. Create a polygon from the vertices on the vertex stack and push it
  310. onto the polygon stack. The vertex stack is empty and ready for a new
  311. polygon definition after this operation.
  312. .br
  313. If a vertex in the polygon is already defined in a previous polygon
  314. that belongs to the same surface, the same vertex will be referenced,
  315. i.e. vertices shared between polygons are only stored once, but they
  316. must be repeated when defining the polygons.
  317. X
  318. .IP \fISurface\ *surface_create(surf_desc,\ shader)\fR
  319. .br
  320. \fIvoid\ *surf_desc;\fR
  321. .br
  322. \fIShader\ *shader;\fR
  323. .sp
  324. Create a surface from the polygons on the polygon stack. A pointer
  325. to the newly-created surface is returned. The polygon stack is empty
  326. afterwards. \fIshader\fR is a pointer to the shader function that
  327. will be called when a point on this surface is to be rendered. See the
  328. section \fBSHADER FUNCTIONS\fR for a declaration of the shader function.
  329. \fIsurf_desc\fR is a pointer to a static structure that contains the
  330. surface properties of the surface. The exact representation of this
  331. structure can be chosen freely by the user depending on the
  332. implementation of his shader. If the internal shader,
  333. \fIbasic_shader\fR is used, this struct is of type \fISurf_desc\fR.
  334. X
  335. .IP \fISurface\ *surface_basic_create(ambient,\ red,\ grn,\ blu,\ specular,\ c3)\fR
  336. .br
  337. \fIdouble\ ambient;\fR
  338. .br
  339. \fIdouble\ red,\ grn,\ blu;\fR
  340. .br
  341. \fIdouble\ specular;\fR
  342. .br
  343. \fIdouble\ c3;\fR
  344. .sp
  345. Create a surface from the polygons on the polygon stack.  A pointer to
  346. the newly-created surface is returned.  The surface will be shaded
  347. with the internal shader, \fIbasic_shader\fR, using the parameters as
  348. values in a \fISurf_desc\fR struct.
  349. X
  350. .IP \fIvoid\ surface_set_shader(surface,\ surf_desc,\ shader)\fR
  351. .br
  352. \fISurface\ *surface;\fR
  353. .br
  354. \fIvoid\    *surf_desc;\fR
  355. .br
  356. \fIShader\  *shader;\fR
  357. .sp
  358. Set the surface \fIsurface\fR to be shaded with the shading function
  359. \fIshader\fR. The shading information used by the shader is pointed at
  360. by \fIsurf_desc\fR.
  361. X
  362. .IP \fIvoid\ surface_basic_shader(surface,\ ambient,\ red,\ grn,\ blu,\ specular,\ c3)\fR
  363. .br
  364. \fISurface\ *surface;\fR
  365. .br
  366. \fIdouble\  ambient;\fR
  367. .br
  368. \fIdouble\  red,\ grn,\ blu;\fR
  369. .br
  370. \fIdouble\  specular;\fR
  371. .br
  372. \fIdouble\  c3;\fR
  373. .sp
  374. Set \fIsurface\fR to be shaded by the internal shader and let
  375. \fIambient\fR, \fIred\fR, \fIgrn\fR, \fIblu\fR, \fIspecular\fR and
  376. \fIc3\fR be the values stored in the \fISurf_desc\fR struct for this
  377. surface. 
  378. X
  379. .IP \fIObject\ *object_create()\fR
  380. Create an empty object, i.e. an object with no surfaces or subobjects
  381. in it. The transformation matrix in the new object will be a identity
  382. matrix initially.
  383. X
  384. .IP \fIObject\ *object_instance(obj)\fR
  385. .br
  386. \fIObject\ *obj;\fR
  387. .sp
  388. Create a new instance of a previously defined object. The lists of
  389. surfaces and subobjects in \fIobj\fR are not copied, but a new
  390. reference with its own transformation matrix is created. The matrix is
  391. set to the identity matrix. If \fIobj\fR is changed, i.e. if one of its
  392. subobjects or surfaces are transformed, one is deleted or added, the
  393. change will also be seen in the copy.
  394. X
  395. .IP \fIObject\ *object_dup(obj)\fR
  396. .br
  397. \fIObject\ *obj;\fR
  398. .sp
  399. Copy recursively an object and its subobjects. The
  400. surfaces in the object tree are not copied, only new references to them
  401. are made.
  402. X
  403. .IP \fIObject\ *object_deep_dup(obj)\fR
  404. .br
  405. \fIObject\ *obj;\fR
  406. .sp
  407. Copy the entire tree for the object \fIobj\fR, including subobjects
  408. and all surfaces, polygons and vertices. This is a costly operation if
  409. the object is complex.
  410. X
  411. .IP \fIvoid\ object_delete(obj)\fR
  412. .br
  413. \fIObject\ *obj;\fR
  414. .sp
  415. Delete the object \fIobj\fR, i.e. the memory used by \fIobj\fR and
  416. all its subobjects and surfaces is recursively freed. \fIsipp\fR keeps
  417. track of internal references so objects and surfaces referenced
  418. from somewhere else in \fIsipp\fR will not be deleted, i.e. no dangling
  419. references are created in the data structures.
  420. X
  421. .IP \fIvoid\ object_install(obj)\fR
  422. .br
  423. \fIObject\ *obj;\fR
  424. .sp
  425. Install the object \fIobj\fR into the rendering database. This
  426. function must be called on all objects that are to be visible in the
  427. rendered image.
  428. X
  429. .IP \fIvoid\ object_uninstall(obj)\fR
  430. .br
  431. \fIObject\ *obj;\fR
  432. .sp
  433. Remove the object \fIobj\fR from the rendering database. If \fIobj\fR
  434. is not in the database to begin with, nothing happens.
  435. X
  436. .IP \fIvoid\ object_add_surface(obj,\ surf)\fR
  437. .br
  438. \fIObject\  *obj;\fR
  439. .br
  440. \fISurface\ *surf;\fR
  441. .sp
  442. Add the surface \fIsurf\fR to the object \fIobj\fR.
  443. X
  444. .IP \fIvoid\ object_sub_surface(obj,\ surf)\fR
  445. .br
  446. \fIObject\  *obj;\fR
  447. .br
  448. \fISurface\ *surf;\fR
  449. .sp
  450. Remove the surface \fIsurf\fR from the object \fIobj\fR.
  451. X
  452. .IP \fIvoid\ object_add_subobj(obj,\ subobj)\fR
  453. .br
  454. \fIObject\ *obj;\fR
  455. .br
  456. \fIObject\ *subobj;\fR
  457. .sp
  458. Add the subobject \fIsubobj\fR to the object \fIobj\fR.
  459. X
  460. .IP \fIvoid\ object_add_subobj(obj,\ subobj)\fR
  461. .br
  462. \fIObject\ *obj;\fR
  463. .br
  464. \fIObject\ *subobj;\fR
  465. .sp
  466. Remove the subobject \fIsubobj\fR from the object \fIobj\fR. It is only 
  467. unlinked from the list of subobjects in \fIobj\fR. If the memory it uses
  468. should be freed, \fIobject_delete()\fR must be used.
  469. X
  470. .IP \fIvoid\ object_set_transf(obj,\ matrix)\fR
  471. .br
  472. \fIObject\     *obj;\fR
  473. .br
  474. \fITransf_mat\ *matrix;\fR
  475. .sp
  476. Set the transformation matrix of the object \fIobj\fR to \fImatrix\fR.
  477. .br
  478. X
  479. .IP \fITransf_mat\ *object_get_transf(obj,\ matrix)\fR
  480. .br
  481. \fIObject\     *obj;\fR
  482. .br
  483. \fITransf_mat\ *matrix;\fR
  484. .sp
  485. Return the transformation matrix currently stored in the object \fIobj\fR. If
  486. \fImatrix\fR is not NULL, the transformation matrix will be copied to that
  487. location and a pointer to it (identical to \fImatrix\fR) is returned. If
  488. \fImatrix\fR is NULL a new matrix will be allocated, the transformation matrix
  489. copied into it and a pointer to the new matrix is returned.
  490. .br
  491. X
  492. .IP \fIvoid\ object_clear_transf(obj)\fR
  493. .br
  494. \fIObject\     *obj;\fR
  495. .sp
  496. Set the transformation matrix of the object \fIobj\fR to the unit matrix.
  497. .br
  498. X
  499. .IP \fIvoid\ object_transform(obj,\ matrix)\fR
  500. .br
  501. \fIObject\     *obj;\fR
  502. .br
  503. \fITransf_mat\ *matrix;\fR
  504. .sp
  505. Post multiply the matrix \fImatrix\fR into the transformation matrix
  506. of the object \fIobj\fR.
  507. X
  508. .br
  509. X
  510. .IP \fIvoid\ object_rot_x(obj,\ ang)\fR
  511. .br
  512. \fIObject\  *obj;\fR
  513. .br
  514. \fIdouble\  ang;\fR
  515. .sp
  516. Rotate the object \fIobj\fR the angle \fIang\fR about the X axis.
  517. \fIang\fR is expressed in radians.
  518. X
  519. .IP \fIvoid\ object_rot_y(obj,\ ang)\fR
  520. .br
  521. \fIObject\  *obj;\fR
  522. .br
  523. \fIdouble\  ang;\fR
  524. .sp
  525. Rotate the object \fIobj\fR the angle \fIang\fR about the Y axis.
  526. \fIang\fR is expressed in radians.
  527. X
  528. .IP \fIvoid\ object_rot_z(obj,\ ang)\fR
  529. .br
  530. \fIObject\  *obj;\fR
  531. .br
  532. \fIdouble\  ang;\fR
  533. .sp
  534. Rotate the object \fIobj\fR the angle \fIang\fR about the Z axis.
  535. \fIang\fR is expressed in radians.
  536. X
  537. .IP \fIvoid\ object_rot(obj,\ point,\ vec,\ ang)\fR
  538. .br
  539. \fIObject\ *obj;\fR
  540. .br
  541. \fIVector\ *point;\fR
  542. .br
  543. \fIVector\ *vec;\fR
  544. .br
  545. \fIdouble\ ang;\fR
  546. .sp
  547. Rotate the object \fIobj\fR the angle \fIang\fR about the line
  548. given by the point \fIpoint\fR and the vector \fIvec\fR starting in
  549. that point. \fIang\fR is expressed in radians.
  550. .br
  551. X
  552. .IP \fIvoid\ object_scale(obj,\ xscale,\ yscale,\ zscale)\fR
  553. .br
  554. \fIObject\ *obj;\fR
  555. .br
  556. \fIdouble\ xscale,\ yscale,\ zscale;\fR
  557. .sp
  558. Scale the object \fIobj\fR with the scaling factors \fIxscale,\
  559. yscale\fR and \fIzscale\fR in the main directions respectively.
  560. X
  561. .IP \fIvoid\ object_move(obj,\ dx,\ dy,\ dz)\fR
  562. .br
  563. \fIObject\ *obj;\fR
  564. .br
  565. \fIdouble\ dx,\ dy,\ dz;\fR
  566. .sp
  567. Move (translate) the object \fIobj\ dx,\ dy\fR and \fIdz\fR in the
  568. three main directions, respectively.
  569. X
  570. .IP \fIvoid\ lightsource_push(x,\ y,\ z,\ intensity)\fR
  571. .br
  572. \fIdouble\ x,\ y,\ z;\fR
  573. .br
  574. \fIdouble\ intensity;\fR
  575. .sp
  576. Create a new lightsource in the scene. All lightsources is considered
  577. to be at an infinit distance and to emit white light. \fIx,\ y,\ z\fR
  578. defines a vector pointing to the lightsource. \fIintensity\fR is a
  579. double between 0 and 1 that defines the intensity of the light coming
  580. from the lightsource.
  581. X
  582. .IP \fIvoid\ view_from(x,\ y,\ z)\fR
  583. .br
  584. .I double x, y, z;
  585. .sp
  586. Define the position of the viewpoint.
  587. X
  588. .IP \fIvoid\ view_at(x,\ y,\ z)\fR
  589. .br
  590. .I double x, y, z;
  591. .sp
  592. Define the viewing direction as going from the viewpoint to the point
  593. .I x, y, z.
  594. X
  595. .IP \fIvoid\ view_up(x,\ y,\ z)\fR
  596. .br
  597. .I double x, y, z;
  598. .sp
  599. Define the up vector. The only constraint on this vector is that it
  600. must not be parallel to the vector going from the viewpoint to the
  601. viewed point.  If this function is not called, the default up vector
  602. is the world Y axis.
  603. X
  604. .IP \fIvoid\ view_focal(ratio)\fR
  605. .br
  606. .I double ratio;
  607. .sp
  608. Define the focal ratio of the "camera". This is the ratio between the
  609. distance from the viewpoint to the screen and half the screen height.
  610. .sp 4
  611. .nf
  612. X                screen
  613. X                |
  614. X                | d
  615. viewpoint            |
  616. .tc -
  617. *                |
  618. .tc
  619. X        s        |
  620. X                |
  621. X                |
  622. .sp 2
  623. focal_ratio = d / s
  624. .sp
  625. .fi
  626. Another way of describing the value is acrtan(v/2) where v is the opening
  627. angle of the view.
  628. .br
  629. Note: The same focal ratio is used both horizontally and vertically.
  630. If the picture is rendered with different resolution in x and y, the ratio
  631. is assumed to be related to the \fIsmallest\fR of the two.
  632. X
  633. .IP \fIviewpoint(x,\ y,\ z,\ to_x,\ to_y,\ to_z,\ up_x,\ up_y,\ up_z,\ focal_ratio)\fR
  634. .br
  635. This function is used to set all viewpoint related values in one call. All
  636. arguments are doubles.
  637. .br
  638. .I x, y, z
  639. is the position of the viewpoint as in \fIview_from()\fR.
  640. .br
  641. .I to_x, to_y, to_z
  642. defines the viewing direction as in \fIview_at()\fR.
  643. .br
  644. .I up_x, up_y, up_z
  645. defines the up vector as in \fIview_up()\fR.
  646. .br
  647. .I focal_ratio
  648. defines (guess what) the focal ratio as in \fIview_focal()\fR.
  649. X
  650. .IP \fIvoid\ render_image_file(xsize,\ ysize,\ outfile,\ mode,\ oversampling)\fR
  651. .br
  652. \fIint\    xsize, ysize;\fR
  653. .br
  654. \fIFILE\ *outfile;\fR
  655. .br
  656. \fIint\    mode;\fR
  657. .br
  658. \fIint\    oversampling;\fR
  659. .sp
  660. This function does the actual rendering of a scene. The image is created with
  661. size (\fIxsize\fR X \fIysize\fR). \fIoutfile\fR is an open file pointer to
  662. which the image will be written.  It can just as well be a pipe of course.
  663. \fImode\fR decides in which mode the image should be rendered and should be
  664. one of \fIPHONG,\ GOURAUD,\ FLAT\fR or \fILINE\fR.  \fIoversampling\fR controls
  665. how much oversampling should be done for anti-aliasing. Each pixel will be the
  666. average of a \fIoversampling\fR X \fIoversampling\fR matrix of subpixels. In
  667. \fILINE\fR mode the \fIoversampling\fR argument is ignored.
  668. X
  669. .IP \fIvoid\ render_image_pixmap(xsize,\ ysize,\ pixmap,\ plot_func,\ mode,\ oversampling)\fR
  670. .br
  671. \fIint\    xsize, ysize;\fR
  672. .br
  673. \fIvoid\ *pixmap;\fR
  674. .br
  675. \fIvoid\ (*plot_func)();\fR
  676. .br
  677. \fIint\    mode;\fR
  678. .br
  679. \fIint\    oversampling;\fR
  680. .sp
  681. This function also does rendering of a scene but the image is rendered into a
  682. pixmap instead of a file. It does not have to be a pixmap though. Anything
  683. where it is possible to plot a pixel (or a line) could be used, e.g. a window
  684. or a PostScript file. \fIxsize\fR, \fIysize\fR, \fImode\fR and
  685. \fIoversampling\fR has the same meaning as in \fIrender_image_file()\fR.
  686. \fIpixmap\fR is a pointer to a structure of any type, representing the pixmap.
  687. \fIplot_func\fR is, unless \fImode\fR is \fILINE\fR, a pointer to a function
  688. that sets a pixel in a pixmap of the same type as \fIpixmap\fR. If \fImode\fR
  689. is \fILINE\fR, it should be a pointer to a function that draws a line in the
  690. pixmap.
  691. .sp
  692. The point plotting function should be defined thus:
  693. .sp
  694. \fIvoid\ plot_func(pixmap,\ x,\ y,\ red,\ green,\ blue)\fR
  695. .br
  696. \       \fImy_pixmap_type\ *pixmap;\fR
  697. .br
  698. \       \fIint\             x,\ y;\fR
  699. .br
  700. \       \fIunsigned\ char\  red,\ green,\ blue;\fR
  701. .sp
  702. and the line drawing function like this:
  703. .sp
  704. \fIvoid\ plot_func(pixmap,\ x1,\ y1,\ x2,\ y2)\fR
  705. .br
  706. \       \fImy_pixmap_type\ *pixmap;\fR
  707. .br
  708. \       \fIint\             x1,\ y1;\fR
  709. .br
  710. \       \fIint\             x2,\ y2;\fR
  711. .br
  712. X
  713. .IP \fIvoid\ render_image(xsize,\ ysize,\ outfile)\fR
  714. .br
  715. \fIint\    xsize, ysize;\fR
  716. .br
  717. \fIFILE\ *outfile;\fR
  718. .sp
  719. This is equivalent to calling \fIrender_image_file()\fR with
  720. \fImode\fR = \fIPHONG\fR and \fIoversampling\fR = 2. This is a macro
  721. which is provided for compatibility with older versions (2.0.2 and
  722. older).
  723. X
  724. .IP \fIvoid\ basic_shader(nx,\ ny,\ nz,\ \ u,\ v,\ w,\ view_vec,\fR
  725. .br
  726. \fI                 lights,\ surface,\ color)\fR
  727. .br
  728. \fIdouble nx, ny, nz;\fR
  729. .br
  730. \fIdouble u, v, w;\fR
  731. .br
  732. \fIVector\ view_vec;\fR
  733. .br
  734. \fILightsource *lights;\fR
  735. .br
  736. \fISurf_desc *surface;\fR
  737. .br
  738. \fI
  739. Color\ *color;\fR
  740. .sp
  741. This is the basic shader function that is provided with the library.
  742. See the section about \fBSHADING FUNCTIONS\fR for more details.
  743. X
  744. .SH SEE ALSO
  745. shaders(3X) - a number of shaders for \fIsipp\fR.
  746. .br
  747. geometric(3X) - Vector and matrix functions for the sipp(3X) library
  748. .br
  749. primitives(3X) - a collection of geometric primitives for \fIsipp\fR.
  750. .br
  751. sipp_pixmap(3X) - pixmap handling code for \fIsipp\fR.
  752. .br
  753. sipp_bitmap(3X) - bitmap handling code for \fIsipp\fR.
  754. X
  755. .SH AUTHORS
  756. Jonas Yngvesson\    \    (jonas-y@isy.liu.se)
  757. .br
  758. Inge Wallin\        (ingwa@isy.liu.se)
  759. X
  760. .SH BUGS
  761. When flat shading is used, the normal vector that is sent to the shader
  762. is not really the polygon normal. It is the average normal at one of
  763. the vertices of the polygon.
  764. .sp
  765. The viewing vector which is sent to the shader is
  766. actually only an approximation which assumes the viewpoint being at infinite
  767. distance. 
  768. .sp
  769. No information is sent to the shader about how big interpolation steps
  770. are in the texture coordinate system. This makes it impossible to use
  771. any filtering techniqe for texture mapping, e.g. summed area tables.
  772. SHAR_EOF
  773. chmod 0664 doc/sipp.man ||
  774. echo 'restore of doc/sipp.man failed'
  775. Wc_c="`wc -c < 'doc/sipp.man'`"
  776. test 25439 -eq "$Wc_c" ||
  777.     echo 'doc/sipp.man: original size 25439, current size' "$Wc_c"
  778. fi
  779. # ============= doc/sipp_pixmap.man ==============
  780. if test -f 'doc/sipp_pixmap.man' -a X"$1" != X"-c"; then
  781.     echo 'x - skipping doc/sipp_pixmap.man (File already exists)'
  782. else
  783. echo 'x - extracting doc/sipp_pixmap.man (Text)'
  784. sed 's/^X//' << 'SHAR_EOF' > 'doc/sipp_pixmap.man' &&
  785. .\" Copyright 1990, Jonas Yngvesson, Inge Wallin
  786. .\" This program and documentation may be distributed freely under
  787. .\" the terms of GNU GENERAL PUBLIC LICENSE.
  788. .TH PIXMAP 3X "July , 1991" 3X
  789. .SH NAME
  790. sipp_pixmap - pixmap handling code for \fIsipp\fR.
  791. .br
  792. sipp_bitmap - bitmap handling code for \fIsipp\fR.
  793. X
  794. .SH SYNOPSIS
  795. \fI#include <sipp_pixmap.h>\fR
  796. .br
  797. or
  798. .br
  799. \fI#include <sipp_bitmap.h>\fR
  800. .sp
  801. [g]cc [\fIflags\fR] \fIfiles\fR -lsipp -lm [ \fIlibraries\fR ]
  802. X
  803. .SH DESCRIPTION
  804. The sipp(3X) library has provisions to create an image in a pixmap in
  805. core.  The most common use of this will probably be rendering into X
  806. bitmaps, Macintosh bitmaps or something similar but for those who do
  807. not want to use system dependent pixmaps we provide the
  808. \fISipp_pixmap\fR.  When rendering a line image the target is a bitmap
  809. file or a bitmap in core rather than a pixmap.  To faciliate this, we
  810. also provide a bitmap implementation, the \fISipp_bitmap\fR.
  811. X
  812. .SH PIXMAP     
  813. A \fISipp_pixmap\fR is defined like this:
  814. .sp
  815. .IP
  816. \fItypedef\ struct {\fR
  817. .br
  818. \fI    int   width;\fR        /* Width of the pixmap */
  819. .br
  820. \fI    int   height;\fR        /* Height of the pixmap */
  821. .br
  822. \fI    u_char * buffer;\fR    /* A pointer to the image. */
  823. .br
  824. \fI}\ Sipp_pixmap;\fR
  825. X
  826. The pointer \fIbuffer\fR is a pointer to the image where each pixel is
  827. stored as three unsigned chars in the order red, green blue.  Thus, the
  828. buffer is 3 * \fIwidth\fR * \fIheight\fR bytes long.
  829. X
  830. The following functions operate on a \fISipp_pixmap\fR:
  831. X
  832. .IP \fISipp_pixmap\ *sipp_pixmap_create(width,\ height)\fR
  833. .br
  834. \fIint\ width;\fR
  835. .br
  836. \fIint\ height;\fR
  837. .sp
  838. Returns a new \fISipp_pixmap\fR with the given size.  The memory used
  839. is allocated using malloc(3).
  840. X
  841. .IP \fIvoid\ sipp_pixmap_destruct(pm)\fR
  842. .br
  843. \fISipp_pixmap\ *pm;\fR
  844. .sp
  845. Frees all memory associated to the \fISipp_pixmap pm\fR.
  846. X
  847. .IP \fIvoid\ sipp_pixmap_set_pixel(pm,\ x,\ y,\ red,\ grn,\ blu)\fR
  848. .br
  849. \fISipp_pixmap\ *pm;\fR
  850. .br
  851. \fIint\ x;\fR
  852. .br
  853. \fIint\ y;\fR
  854. .br
  855. \fIu_char\ red;\fR
  856. .br
  857. \fIu_char\ grn;\fR
  858. .br
  859. \fIu_char\ blu\fR
  860. .sp
  861. Set the pixel at (\fIx\fR, \fIy\fR) in pixmap \fIpm\fR to be the color
  862. (\fIred\fR, \fIgrn\fR, \fIblu\fR).
  863. X
  864. .IP \fIvoid\ sipp_pixmap_write(file,\ pm)\fR
  865. .br
  866. \fIFILE\ *file;\fR
  867. .br
  868. \fISipp_pixmap\ *pm\fR
  869. .sp
  870. Write the pixmap \fIpm\fR to the open file \fIfile\fR.  The image is
  871. written in the Portable Pixmap format (ppm), the same format sipp is
  872. using when rendering to a file.
  873. X
  874. .SH BITMAP     
  875. A \fISipp_bitmap\fR is defined like this:
  876. .sp
  877. .IP
  878. \fItypedef\ struct {\fR
  879. .br
  880. \fI    int   width;\fR        /* Width of the bitmap in pixels */
  881. .br
  882. \fI    int   height;\fR        /* Height of the bitmap in pixels */
  883. .br
  884. \fI    int   width_bytes;\fR    /* Width of the bitmap in bytes. */
  885. .br
  886. \fI    u_char * buffer;\fR    /* A pointer to the image. */
  887. .br
  888. \fI}\ Sipp_bitmap;\fR
  889. X
  890. The pointer \fIbuffer\fR is a pointer to the image where each pixel is
  891. a bit in an unsigned char.  If the \fIwidth\fR field is not a multiple
  892. of 8, the last bits in the last byte of a row are not used.  The most
  893. significant bit in each byte is the leftmost pixel. The entire buffer
  894. is \fIwidth_bytes\fR * \fIheight\fR bytes long.
  895. X
  896. The following functions operate on a \fISipp_bitmap\fR:
  897. X
  898. .IP \fISipp_bitmap\ *sipp_bitmap_create(width,\ height)\fR
  899. .br
  900. \fIint\ width;\fR
  901. .br
  902. \fIint\ height;\fR
  903. .sp
  904. Returns a new \fISipp_bitmap\fR with the given size.  The memory used
  905. is allocated using malloc(3).
  906. X
  907. .IP \fIvoid\ sipp_bitmap_destruct(bm)\fR
  908. .br
  909. \fISipp_bitmap\ *bm;\fR
  910. .sp
  911. Frees all memory associated to the \fISipp_bitmap bm\fR.
  912. X
  913. .IP \fIvoid\ sipp_bitmap_line(bm,\ x1,\ y1,\ x2,\ y2)\fR
  914. .br
  915. \fISipp_bitmap\ *bm;\fR
  916. .br
  917. \fIint\ x1;\fR
  918. .br
  919. \fIint\ y1;\fR
  920. .br
  921. \fIint\ x2;\fR
  922. .br
  923. \fIint\ y2;\fR
  924. .sp
  925. Draw a line from (\fIx1\fR,\ \fIy1\fR) to (\fIx2\fR,\ \fIy2\fR) in
  926. the bitmap \fIbm\fR.
  927. X
  928. .IP \fIvoid\ sipp_bitmap_write(file,\ bm)\fR
  929. .br
  930. \fIFILE\ *file;\fR
  931. .br
  932. \fISipp_bitmap\ *bm\fR
  933. .sp
  934. Write the bitmap \fIbm\fR to the open file \fIfile\fR.  The image is
  935. written in the Portable Bitmap format (pbm), the same format sipp is
  936. using when rendering a line drawing to a file.
  937. X
  938. .SH SEE ALSO
  939. sipp(3X) - simple polygon processor, a 3d-graphics library
  940. .br
  941. geometric(3X) - Vector and matrix functions for the sipp(3X) library
  942. .br
  943. primitives(3X) - a collection of geometric primitives for \fIsipp\fR.
  944. .br
  945. shaders(3X) - a collection of shaders for \fIsipp\fR.
  946. X
  947. .SH AUTHORS
  948. Jonas Yngvesson\    \    (jonas-y@isy.liu.se)
  949. .br
  950. Inge Wallin\        (ingwa@isy.liu.se)
  951. X
  952. .SH BUGS
  953. No known bugs.
  954. SHAR_EOF
  955. chmod 0644 doc/sipp_pixmap.man ||
  956. echo 'restore of doc/sipp_pixmap.man failed'
  957. Wc_c="`wc -c < 'doc/sipp_pixmap.man'`"
  958. test 4438 -eq "$Wc_c" ||
  959.     echo 'doc/sipp_pixmap.man: original size 4438, current size' "$Wc_c"
  960. fi
  961. # ============= demo/Makefile ==============
  962. if test ! -d 'demo'; then
  963.     echo 'x - creating directory demo'
  964.     mkdir 'demo'
  965. fi
  966. if test -f 'demo/Makefile' -a X"$1" != X"-c"; then
  967.     echo 'x - skipping demo/Makefile (File already exists)'
  968. else
  969. echo 'x - extracting demo/Makefile (Text)'
  970. sed 's/^X//' << 'SHAR_EOF' > 'demo/Makefile' &&
  971. #
  972. # Makefile for the misc demos of sipp version 2.0.
  973. #
  974. X
  975. # These values are used if not overruled from the command line
  976. CC = cc
  977. #CFLAGS = -O -I../libsipp
  978. CFLAGS = -g -I../libsipp
  979. X
  980. SHELL = /bin/sh
  981. RM = rm -f
  982. X
  983. SRCS = torustest.c conetest.c ellipsoid.c prismtest.c chain.c \
  984. X    teapot.c structure.c planettest.c isy90.c strausstest.c woodtest.c
  985. PROGRAMS = torustest conetest ellipsoid prismtest chain \
  986. X    teapot structure planettest isy90 strausstest woodtest
  987. X
  988. X
  989. all:
  990. X    @echo "If you want to make only the pretty images, type 'make pretty'."
  991. X    @echo "If you want to make only the test images, type   'make tests'."
  992. X    @echo "If you want to make all images, type             'make images'."
  993. X    @echo
  994. X    @echo "If you want to make the programs, but not the images,"
  995. X    @echo "type 'make programs'."
  996. X    @echo
  997. X
  998. X
  999. # ================================================================
  1000. X
  1001. X
  1002. programs: ../libsipp/libsipp.a $(PROGRAMS)
  1003. X
  1004. ../libsipp/libsipp.a:
  1005. X    cd ..; $(MAKE) library
  1006. X
  1007. X
  1008. # ================================================================
  1009. X
  1010. X
  1011. teapot: teapot.o ../libsipp/libsipp.a
  1012. X    $(CC) -o teapot teapot.o ../libsipp/libsipp.a -lm
  1013. X    
  1014. chain: chain.o ../libsipp/libsipp.a
  1015. X    $(CC) -o chain chain.o ../libsipp/libsipp.a -lm
  1016. X
  1017. structure: structure.o ../libsipp/libsipp.a
  1018. X    $(CC) -o structure structure.o ../libsipp/libsipp.a -lm
  1019. X
  1020. planettest: planettest.o ../libsipp/libsipp.a
  1021. X    $(CC) -o planettest planettest.o ../libsipp/libsipp.a -lm
  1022. X
  1023. isy90: isy90.o ../libsipp/libsipp.a
  1024. X    $(CC) -o isy90 isy90.o ../libsipp/libsipp.a -lm
  1025. X
  1026. ellipsoid:    ellipsoid.o ../libsipp/libsipp.a
  1027. X    $(CC) -o ellipsoid ellipsoid.o ../libsipp/libsipp.a -lm
  1028. X
  1029. torustest: torustest.o ../libsipp/libsipp.a
  1030. X    $(CC) -o torustest torustest.o ../libsipp/libsipp.a -lm
  1031. X
  1032. conetest: conetest.o ../libsipp/libsipp.a
  1033. X    $(CC) -o conetest conetest.o ../libsipp/libsipp.a -lm
  1034. X
  1035. prismtest: prismtest.o ../libsipp/libsipp.a
  1036. X    $(CC) -o prismtest prismtest.o ../libsipp/libsipp.a -lm
  1037. X
  1038. strausstest: strausstest.o ../libsipp/libsipp.a
  1039. X    $(CC) -o strausstest strausstest.o ../libsipp/libsipp.a -lm
  1040. X
  1041. woodtest: woodtest.o ../libsipp/libsipp.a
  1042. X    $(CC) -o woodtest woodtest.o ../libsipp/libsipp.a -lm
  1043. X
  1044. X
  1045. # ================================================================
  1046. X
  1047. X
  1048. clean:
  1049. X    $(RM) *~ .*~ *.o $(PROGRAMS) *.p?m TAGS
  1050. X
  1051. tags:
  1052. X    etags $(SRCS)
  1053. X
  1054. X
  1055. # ================================================================
  1056. X
  1057. PRETTY = chain.ppm teapot.ppm structure.ppm planet.ppm isy90.ppm
  1058. TESTS = torus.ppm cone.ppm ellipsoid.ppm prism.ppm strauss.ppm wood.ppm
  1059. IMAGES = $(PRETTY) $(TESTS)
  1060. X
  1061. images: $(IMAGES)
  1062. pretty: $(PRETTY)
  1063. tests:  $(TESTS)
  1064. X
  1065. chain.ppm: chain
  1066. X    chain 
  1067. teapot.ppm: teapot
  1068. X    teapot 
  1069. structure.ppm: structure
  1070. X    structure
  1071. planet.ppm: planettest
  1072. X    planettest
  1073. isy90.ppm: isy90
  1074. X    isy90
  1075. torus.ppm: torustest
  1076. X    torustest
  1077. cone.ppm: conetest
  1078. X    conetest
  1079. ellipsoid.ppm: ellipsoid
  1080. X    ellipsoid
  1081. prism.ppm: prismtest
  1082. X    prismtest
  1083. strauss.ppm: strausstest
  1084. X    strausstest
  1085. wood.ppm: woodtest
  1086. X    woodtest
  1087. SHAR_EOF
  1088. chmod 0664 demo/Makefile ||
  1089. echo 'restore of demo/Makefile failed'
  1090. Wc_c="`wc -c < 'demo/Makefile'`"
  1091. test 2878 -eq "$Wc_c" ||
  1092.     echo 'demo/Makefile: original size 2878, current size' "$Wc_c"
  1093. fi
  1094. # ============= demo/README ==============
  1095. if test -f 'demo/README' -a X"$1" != X"-c"; then
  1096.     echo 'x - skipping demo/README (File already exists)'
  1097. else
  1098. echo 'x - extracting demo/README (Text)'
  1099. sed 's/^X//' << 'SHAR_EOF' > 'demo/README' &&
  1100. This directory contains test programs and demonstration programs for
  1101. the sipp library version 2.1. The images here can be divided into two
  1102. categories: the mere test images (boring) and the demonstrations
  1103. images (impressive).
  1104. X
  1105. All the testprograms takes the following switches:
  1106. X
  1107. X        -p      Render with PHONG shading.
  1108. X        -g      Render with GOURAUD shading.
  1109. X        -f      Render with FLAT shading.
  1110. X        -l      Render a LINE image.
  1111. X        -s n    Make the image (n X n) pixels big.
  1112. X
  1113. If no switches are given, the default is to render a (256 X 256) pixels
  1114. big image with PHONG shading. Note that if "-l" is used, the resulting
  1115. image will be a bitmap and have ".pbm" as extension instead of ".ppm".
  1116. X
  1117. X
  1118. Test image              Created by      Explanation
  1119. ---------------------------------------------------
  1120. torus.ppm               torustest       A plain violet torus
  1121. cone.ppm                conetest        One ordinary cone, one truncated
  1122. X                                        and one cylinder.
  1123. ellipsoid.ppm           ellipsoid       A violet course ellipsoid.
  1124. X                                        Note how the surface of the
  1125. X                                        ellipsoid appears smooth in
  1126. X                                        spite of the low number of
  1127. X                                        polygons in it (PHONG mode).
  1128. prism.ppm               prismtest       Three orange prisms of various form.
  1129. strauss.ppm             strausstest     Demo of the strauss_shader(). Four
  1130. X                                        spheres with the same color but
  1131. X                                        different smoothness and metalness.
  1132. wood.ppm                woodtest        Demo of the wood shader.
  1133. X
  1134. Demo image              Created by      Explanation
  1135. ---------------------------------------------------
  1136. chain.ppm               chain           A 3-D chain of torii.
  1137. teapot.ppm              teapot          The standard classic Newell
  1138. X                                        teapot. 
  1139. structure.ppm           structure       A geometric structure,
  1140. X                                        demonstrating "eroded"
  1141. X                                        appearance of a surface
  1142. planet.ppm              planettest      A planet with fractal coasts
  1143. X                                        and clouds.
  1144. isy90.ppm               isy90           The cover of the 1990
  1145. X                                        Activity Report at the Dept.
  1146. X                                        of EE at Linkoping University.  
  1147. X                                        Demonstrates simulated marble and
  1148. X                                        granite texture.
  1149. SHAR_EOF
  1150. chmod 0664 demo/README ||
  1151. echo 'restore of demo/README failed'
  1152. Wc_c="`wc -c < 'demo/README'`"
  1153. test 2643 -eq "$Wc_c" ||
  1154.     echo 'demo/README: original size 2643, current size' "$Wc_c"
  1155. fi
  1156. # ============= demo/animation/Makefile ==============
  1157. if test ! -d 'demo/animation'; then
  1158.     echo 'x - creating directory demo/animation'
  1159.     mkdir 'demo/animation'
  1160. fi
  1161. if test -f 'demo/animation/Makefile' -a X"$1" != X"-c"; then
  1162.     echo 'x - skipping demo/animation/Makefile (File already exists)'
  1163. else
  1164. echo 'x - extracting demo/animation/Makefile (Text)'
  1165. sed 's/^X//' << 'SHAR_EOF' > 'demo/animation/Makefile' &&
  1166. # Makefile for the animation demo.
  1167. X
  1168. LIBDIR=../../libsipp
  1169. X
  1170. CC = cc
  1171. #CFLAGS = -g -I$(LIBDIR)
  1172. CFLAGS = -O4 -I$(LIBDIR)
  1173. X
  1174. PROGS = animation
  1175. X
  1176. X
  1177. all:    $(PROGS)
  1178. X
  1179. clean:
  1180. X    rm -f *.o *~ $(PROGS) anim??.p?m core
  1181. X 
  1182. X
  1183. animation: animation.o
  1184. X    $(CC) -o $@ animation.o -L$(LIBDIR) -lsipp -lm
  1185. X
  1186. SHAR_EOF
  1187. chmod 0664 demo/animation/Makefile ||
  1188. echo 'restore of demo/animation/Makefile failed'
  1189. Wc_c="`wc -c < 'demo/animation/Makefile'`"
  1190. test 273 -eq "$Wc_c" ||
  1191.     echo 'demo/animation/Makefile: original size 273, current size' "$Wc_c"
  1192. fi
  1193. # ============= demo/animation/animation.c ==============
  1194. if test -f 'demo/animation/animation.c' -a X"$1" != X"-c"; then
  1195.     echo 'x - skipping demo/animation/animation.c (File already exists)'
  1196. else
  1197. echo 'x - extracting demo/animation/animation.c (Text)'
  1198. sed 's/^X//' << 'SHAR_EOF' > 'demo/animation/animation.c' &&
  1199. #include <stdio.h>
  1200. #include <math.h>
  1201. X
  1202. #include <geometric.h>
  1203. #include <sipp.h>
  1204. #include <shaders.h>
  1205. #include <primitives.h>
  1206. X
  1207. extern double atof();
  1208. X
  1209. extern char *optarg;
  1210. extern int optind,  opterr;
  1211. X
  1212. X
  1213. #define RESOLUTION    5
  1214. #define FLOORSIZE     15.0
  1215. X
  1216. X
  1217. Marble_desc teapot_surf = {
  1218. X    0.4, 
  1219. X    0.5, 
  1220. X    0.05, 
  1221. X    8.0, 
  1222. X    {0.90, 0.80, 0.65}, 
  1223. X    {0.30, 0.08, 0.08}
  1224. };
  1225. X
  1226. X
  1227. typedef struct {
  1228. X    double   sqsize;
  1229. X    Surf_desc   col1;
  1230. X    Surf_desc   col2;
  1231. } Floor_desc;
  1232. X
  1233. X
  1234. Floor_desc floor_surf = {
  1235. X    1.0, 
  1236. X    { 0.4, 0.0, 0.1, {0.9900, 0.9000, 0.7900} },  /* Eggshell white */
  1237. X    { 0.4, 0.0, 0.1, {0.8300, 0.2400, 0.1000} }      /* English red */
  1238. };
  1239. X
  1240. X
  1241. /*
  1242. X * A shader to produce a checkered floor.
  1243. X */
  1244. X
  1245. static void
  1246. floor_shader(nx, ny, nz, u, v, w, view_vec, lights, fd, color)
  1247. X    double  nx, ny, nz;
  1248. X    double  u, v, w;
  1249. X    Vector  view_vec;
  1250. X    Lightsource *lights;
  1251. X    Floor_desc  *fd;
  1252. X    Color *color;
  1253. {
  1254. X    Surf_desc  * col;
  1255. X    int          intu;
  1256. X    int          intw;
  1257. X
  1258. X    intu = floor(u / fd->sqsize);
  1259. X    if (intu < 0) 
  1260. X    intu = -intu;
  1261. X
  1262. X    intw = floor(w / fd->sqsize);
  1263. X    if (intw < 0) 
  1264. X    intw = -intw;
  1265. X
  1266. X    if ((intu ^ intw) & 1)
  1267. X    col = &fd->col1;
  1268. X    else
  1269. X        col = &fd->col2;
  1270. X
  1271. X    basic_shader(nx, ny, nz, u, v, w, view_vec, lights, col, color);
  1272. }
  1273. X
  1274. X
  1275. X
  1276. main(argc, argv)
  1277. X    int     argc;
  1278. X    char  **argv;
  1279. {
  1280. X    Object  *teapot;        /* The teapot and its parts. */
  1281. X    Object  *handle;
  1282. X    Object  *spout;
  1283. X    Object  *body;
  1284. X    Object  *lid;
  1285. X    Object  *bottom;
  1286. X    Transf_mat  * teapot_transf;
  1287. X
  1288. X    Object  *floor;        /* The floor. */
  1289. X
  1290. X    FILE    *infile;
  1291. X    int      image_size;
  1292. X    FILE    *image;
  1293. X    int      frame;
  1294. X    int      mode;
  1295. X
  1296. X    double   time_start;    /* Animation time values. */
  1297. X    double   time_stop;
  1298. X    double   time_step;
  1299. X    double   time;
  1300. X    double   t_jump;
  1301. X    double   height;
  1302. X    double   t_scale;
  1303. X    double   scaling;
  1304. X    double   angle;
  1305. X    char     filename[256];
  1306. X    char     *file_ext;
  1307. X    char     c;
  1308. X
  1309. X    mode = LINE;
  1310. X    time_start = 0.0;
  1311. X    time_stop  = 1.0;
  1312. X    time_step  = 0.04;
  1313. X    image_size = 256;
  1314. X    file_ext = "pbm";
  1315. X
  1316. X    while ((c = getopt(argc, argv, "pgfls:")) != EOF) {
  1317. X        switch (c) {
  1318. X          case 'p':
  1319. X            mode = PHONG;
  1320. X            file_ext = "ppm";
  1321. X            break;
  1322. X
  1323. X          case 'g':
  1324. X            mode = GOURAUD;
  1325. X            file_ext = "ppm";
  1326. X            break;
  1327. X
  1328. X          case 'f':
  1329. X            mode = FLAT;
  1330. X            file_ext = "ppm";
  1331. X            break;
  1332. X
  1333. X          case 'l':
  1334. X            mode = LINE;
  1335. X            file_ext = "pbm";
  1336. X            break;
  1337. X
  1338. X          case 's':
  1339. X            image_size = atoi(optarg);
  1340. X            break;
  1341. X        }
  1342. X    }
  1343. X
  1344. X
  1345. X    sipp_init();
  1346. X
  1347. X
  1348. X    /* Create the floor. */
  1349. X    floor = sipp_block(FLOORSIZE, 1.0, FLOORSIZE, &floor_surf, floor_shader);
  1350. X    object_move(floor, 0.0, -0.5, 0.0);
  1351. X    object_install(floor);
  1352. X
  1353. X
  1354. X    /* Create the teapot and its parts. */
  1355. X    infile = fopen("../tpt_handle.bez", "r");
  1356. X    handle = sipp_bezier(infile, RESOLUTION, &teapot_surf, marble_shader);
  1357. X    fclose(infile);
  1358. X
  1359. X    infile = fopen("../tpt_spout.bez", "r");
  1360. X    spout = sipp_bezier(infile, RESOLUTION, &teapot_surf, marble_shader);
  1361. X    fclose(infile);
  1362. X
  1363. X    infile = fopen("../tpt_body.bez", "r");
  1364. X    body = sipp_bezier(infile, RESOLUTION, &teapot_surf, marble_shader);
  1365. X    fclose(infile);
  1366. X
  1367. X    infile = fopen("../tpt_lid.bez", "r");
  1368. X    lid = sipp_bezier(infile, RESOLUTION, &teapot_surf, marble_shader);
  1369. X    fclose(infile);
  1370. X
  1371. X    bottom = sipp_cylinder(0.375, 0.01, RESOLUTION * 4, &teapot_surf,
  1372. X                           marble_shader);
  1373. X    object_rot_x(bottom, M_PI / 2.0);
  1374. X
  1375. X    teapot = object_create();
  1376. X    object_add_subobj(teapot, body);
  1377. X    object_add_subobj(teapot, lid);
  1378. X    object_add_subobj(teapot, handle);
  1379. X    object_add_subobj(teapot, spout);
  1380. X    object_add_subobj(teapot, bottom);
  1381. X    object_install(teapot);
  1382. X
  1383. X
  1384. X    /* Lit the stage! */
  1385. X    lightsource_push(0.2, 1.0, 2.0, 1.0);
  1386. X    lightsource_push(1.0, 0.5, 0.0, 0.4);
  1387. X
  1388. X
  1389. X    /* Viewing parameters. */
  1390. X    view_from(16.0, 4.0, 24.0);
  1391. X    view_at(0.0, 1.4, 0.0);
  1392. X    view_up(0.0, 1.0, 0.0);
  1393. X    view_focal(0.0625);
  1394. X
  1395. X
  1396. X    /*
  1397. X     * The following code is quite ugly and full of magic numbers.
  1398. X     * It is basically two parabolas that describe the teapots jump 
  1399. X     * and its "squashing" when it lands.
  1400. X     */
  1401. X    frame = time_start / time_step;
  1402. X    time = frame * time_step;
  1403. X    while (time < time_stop) {
  1404. X
  1405. X        if (time < 0.65) {
  1406. X        /* During the jump */
  1407. X            t_jump = time * 1.94464;
  1408. X            height = 6.2 * t_jump - 9.81 * t_jump * t_jump / 2.0;
  1409. X            angle = 2.0 * M_PI * time / 0.65;
  1410. X            scaling = 1.0;
  1411. X
  1412. X        } else {
  1413. X        /* During the squashing phase. */
  1414. X            height = 0.0;
  1415. X            angle = 0.0;
  1416. X            t_scale = (time - 0.65) * 0.64533;
  1417. X            scaling = 1.0 - 6.2 * t_scale + 54.9 * t_scale * t_scale / 2.0;
  1418. X        }
  1419. X
  1420. X    /* 
  1421. X     * Save the original transformation state of the teapot.
  1422. X     * It is easier to recreate the proper position from scratch
  1423. X     * for each new frame than to calculate the difference between
  1424. X     * one image and the next.
  1425. X     */
  1426. X    teapot_transf = object_get_transf(teapot, NULL);
  1427. X
  1428. X    /* Place the teapot in its proper position. */
  1429. X        object_scale(teapot, 1.0, scaling, 1.0);
  1430. X        object_move(teapot, 0.0, -0.4, 0.0);
  1431. X        object_rot_z(teapot, angle);
  1432. X        object_move(teapot, 0.0, 0.4, 0.0);
  1433. X        object_move(teapot, 0.0, height, 0.0);
  1434. X
  1435. X        sprintf(filename, "anim%02d.%s", frame, file_ext);
  1436. X        image = fopen(filename, "w");
  1437. X        printf("\rRendering frame %2d...", frame);
  1438. X        fflush(stdout);
  1439. X
  1440. X    /* Render the image. */
  1441. X        render_image_file(image_size, image_size, image, mode, 3);
  1442. X        fclose(image);
  1443. X
  1444. X    /* Reset the teapot to its original position and shape. */
  1445. X    object_set_transf(teapot, teapot_transf);
  1446. X
  1447. X        frame++;
  1448. X        time = frame * time_step;
  1449. X    }
  1450. X
  1451. X    printf("done.\n");
  1452. X    exit(0);
  1453. }
  1454. SHAR_EOF
  1455. chmod 0664 demo/animation/animation.c ||
  1456. echo 'restore of demo/animation/animation.c failed'
  1457. Wc_c="`wc -c < 'demo/animation/animation.c'`"
  1458. test 5885 -eq "$Wc_c" ||
  1459.     echo 'demo/animation/animation.c: original size 5885, current size' "$Wc_c"
  1460. fi
  1461. # ============= demo/animation/README ==============
  1462. if test -f 'demo/animation/README' -a X"$1" != X"-c"; then
  1463.     echo 'x - skipping demo/animation/README (File already exists)'
  1464. else
  1465. echo 'x - extracting demo/animation/README (Text)'
  1466. sed 's/^X//' << 'SHAR_EOF' > 'demo/animation/README' &&
  1467. This directory contains a small demonstration of how one can create an
  1468. animation using the SIPP library. When run, it will produce a sequence of 24
  1469. images which is an animation of a somersaulting marble teapot on top of a
  1470. checkered floor.
  1471. X
  1472. The motions are designed to be a "closed loop", i.e. the sequence can be shown
  1473. many consecutive times and the motions should still look continuous.
  1474. X
  1475. The default rendering mode is lines, so that nobody accidently overflows his
  1476. diskspace, but any rendering mode (and image size) can be chosen using the
  1477. same flags as in the other demonstration programs (see ../README).
  1478. SHAR_EOF
  1479. chmod 0664 demo/animation/README ||
  1480. echo 'restore of demo/animation/README failed'
  1481. Wc_c="`wc -c < 'demo/animation/README'`"
  1482. test 608 -eq "$Wc_c" ||
  1483.     echo 'demo/animation/README: original size 608, current size' "$Wc_c"
  1484. fi
  1485. # ============= demo/chain.c ==============
  1486. if test -f 'demo/chain.c' -a X"$1" != X"-c"; then
  1487.     echo 'x - skipping demo/chain.c (File already exists)'
  1488. else
  1489. echo 'x - extracting demo/chain.c (Text)'
  1490. sed 's/^X//' << 'SHAR_EOF' > 'demo/chain.c' &&
  1491. #include <stdio.h>
  1492. #include <math.h>
  1493. X
  1494. #include <sipp.h>
  1495. #include <primitives.h>
  1496. X
  1497. X
  1498. X
  1499. #define SMALLRES 15
  1500. #define BIGRES   39
  1501. X
  1502. extern char *optarg;
  1503. X
  1504. main(argc, argv)
  1505. X    int    argc;
  1506. X    char **argv;
  1507. {
  1508. X    Object  *torus;
  1509. X    Object  *torus_pair;
  1510. X    Object  *chain;
  1511. X    FILE    *fp ;
  1512. X    Surf_desc surf;
  1513. X
  1514. X    char    *imfile_name;
  1515. X    int      mode;
  1516. X    char     c;
  1517. X    int      size;
  1518. X
  1519. X    imfile_name = "chain.ppm";
  1520. X    mode = PHONG;
  1521. X    size = 256;
  1522. X
  1523. X    while ((c = getopt(argc, argv, "pgfls:")) != EOF) {
  1524. X        switch (c) {
  1525. X          case 'p':
  1526. X            mode = PHONG;
  1527. X            imfile_name = "chain.ppm";
  1528. X            break;
  1529. X
  1530. X          case 'g':
  1531. X            mode = GOURAUD;
  1532. X            imfile_name = "chain.ppm";
  1533. X            break;
  1534. X
  1535. X          case 'f':
  1536. X            mode = FLAT;
  1537. X            imfile_name = "chain.ppm";
  1538. X            break;
  1539. X
  1540. X          case 'l':
  1541. X            mode = LINE;
  1542. X            imfile_name = "chain.pbm";
  1543. X            break;
  1544. X
  1545. X          case 's':
  1546. X            size = atoi(optarg);
  1547. X            break;
  1548. X        }
  1549. X    }
  1550. X
  1551. X    sipp_init();
  1552. X
  1553. X    lightsource_push(1.0, 1.0, 1.0, 0.9);
  1554. X    lightsource_push(-1.0, -1.0, 0.5, 0.4);
  1555. X
  1556. X    surf.ambient = 0.5;
  1557. X    surf.color.red = 0.8;
  1558. X    surf.color.grn = 0.6;
  1559. X    surf.color.blu = 0.3;
  1560. X    surf.specular = 0.6;
  1561. X    surf.c3 = 0.2;
  1562. X    
  1563. X    torus = sipp_torus(1.0, 0.23, BIGRES, SMALLRES, &surf, basic_shader);
  1564. X    torus_pair = object_create();
  1565. X    object_add_subobj(torus_pair, torus);
  1566. X    torus = object_instance(torus);
  1567. X    object_move(torus, 0.0, -1.375, 0.0);
  1568. X    object_rot_y(torus, M_PI / 2.0);
  1569. X    object_add_subobj(torus_pair, torus);
  1570. X    
  1571. X    chain = object_create();
  1572. X    object_move(torus_pair, -1.375, 1.375, 0.0);
  1573. X    object_add_subobj(chain, torus_pair);
  1574. X    torus_pair = object_instance(torus_pair);
  1575. X    object_rot_z(torus_pair, M_PI / 2.0);
  1576. X    object_move(torus_pair, -1.375, -1.375, 0.0);
  1577. X    object_add_subobj(chain, torus_pair);
  1578. X    torus_pair = object_instance(torus_pair);
  1579. X    object_rot_z(torus_pair, M_PI);
  1580. X    object_move(torus_pair, 1.375, -1.375, 0.0);
  1581. X    object_add_subobj(chain, torus_pair);
  1582. X    torus_pair = object_instance(torus_pair);
  1583. X    object_rot_z(torus_pair, 3.0 * M_PI / 2.0);
  1584. X    object_move(torus_pair, 1.375, 1.375, 0.0);
  1585. X    object_add_subobj(chain, torus_pair);
  1586. X    
  1587. X    object_install(chain);
  1588. X
  1589. X    view_from(5.0, -2.0, 15.0);
  1590. X    view_at(0.5, 0.0, 0.0);
  1591. X    view_up(0.0, 0.0, 1.0);
  1592. X    view_focal(0.25);
  1593. X
  1594. X    printf("Rendering, wait...");
  1595. X    fflush(stdout);
  1596. X
  1597. X    fp = fopen(imfile_name, "w");
  1598. X    render_image_file(size, size, fp, mode, 2);
  1599. X    printf("Done.\n");
  1600. X
  1601. X    exit(0);
  1602. }
  1603. SHAR_EOF
  1604. chmod 0664 demo/chain.c ||
  1605. echo 'restore of demo/chain.c failed'
  1606. Wc_c="`wc -c < 'demo/chain.c'`"
  1607. test 2581 -eq "$Wc_c" ||
  1608.     echo 'demo/chain.c: original size 2581, current size' "$Wc_c"
  1609. fi
  1610. true || echo 'restore of demo/conetest.c failed'
  1611. echo End of part 7, continue with part 8
  1612. exit 0
  1613.  
  1614. exit 0 # Just in case...
  1615.