BRL-CAD
sh_null.c
Go to the documentation of this file.
1 /* S H _ N U L L . C
2  * BRL-CAD
3  *
4  * Copyright (c) 2004-2014 United States Government as represented by
5  * the U.S. Army Research Laboratory.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * version 2.1 as published by the Free Software Foundation.
10  *
11  * This library is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this file; see the file named COPYING for more
18  * information.
19  */
20 /** @file liboptical/sh_null.c
21  *
22  * Notes -
23  * This is the null, aka invisible, shader. It is potentially useful as a performance
24  * metric as well as to hide objects from a scene rendering. It simply does nothing.
25  *
26  * This is the most basic shader.
27  *
28  */
29 
30 #include "common.h"
31 
32 #include <stdio.h>
33 #include <math.h>
34 #include "vmath.h"
35 #include "raytrace.h"
36 #include "optical.h"
37 
38 
39 HIDDEN int sh_null_setup(register struct region *rp, struct bu_vls *matparm, void **dpp, const struct mfuncs *mfp, struct rt_i *rtip);
40 HIDDEN int sh_null_render(struct application *ap, const struct partition *pp, struct shadework *swp, void *dp);
41 HIDDEN void sh_null_print(register struct region *rp, void *dp);
42 HIDDEN void sh_null_free(void *cp);
43 
44 /* The "mfuncs" table describes what the user interface may call this shader.
45  * The null shader may be referred to as null or invisible. Note that the
46  * four shader functions *must* be defined, even if they do nothing.
47  */
48 struct mfuncs null_mfuncs[] = {
49  {MF_MAGIC, "null", 0, MFI_HIT, 0, sh_null_setup, sh_null_render, sh_null_print, sh_null_free },
50  {MF_MAGIC, "invisible", 0, MFI_HIT, 0, sh_null_setup, sh_null_render, sh_null_print, sh_null_free },
51  {0, (char *)0, 0, 0, 0, 0, 0, 0, 0 }
52 };
53 
54 
55 /*
56  * This routine is called (at prep time) once for each region which uses this
57  * shader. Any shader-specific initialization should be done here. It should
58  * return 1 on success and -1 on failure. Alternatively, this routine should
59  * return 0 to delete this region's shader information after setup (i.e. it's
60  * not needed for whatever reason to it won't be rendered).
61  *
62  * The null shader has nothing to do during setup since it doesn't actually
63  * have anything to do during render0. Its setup returns 0 since there's no
64  * need to keep any region info. This means that sh_null_render will not even
65  * get called.
66  */
67 HIDDEN int
68 sh_null_setup(register struct region *UNUSED(rp), struct bu_vls *UNUSED(matparm), void **UNUSED(dpp), const struct mfuncs *UNUSED(mfp), struct rt_i *UNUSED(rtip))
69 {
70  /* no point to check the arguments since we do nothing with them. we leave the error
71  * checking to elsewhere when used.
72  */
73 
74  /* no point in keeping this region's data around */
75  return 0;
76 }
77 
78 
79 /*
80  * This is called (from viewshade() in shade.c) once for each hit point
81  * to be shaded. The purpose here is to fill in values in the shadework
82  * structure. This is, of course, not necessary when setup returns 0.
83  *
84  * The null shader actually does "something", though it is not called.
85  * It has to at least pass the ray through so that it can actually
86  * raytrace what is visible behind the invisible object. Otherwise,
87  * an empty black void would be rendered. this is not really important
88  * though, since it shouldn't normally be called.
89  */
90 HIDDEN int
91 sh_null_render(struct application *ap, const struct partition *pp, struct shadework *swp, void *UNUSED(dp))
92 {
93  /* check the validity of the arguments we got */
94 
95  RT_AP_CHECK(ap);
96  RT_CHECK_PT(pp);
97 
98  /* shadework structures do not have magic numbers or other means to test
99  * their validity
100  */
101 
102  bu_log("Who called sh_null_render explicitly?");
103 
104  /* here is what actually makes the object invisible/null instead of being a
105  * black void (if render ever is called).
106  */
107  (void)rr_render(ap, pp, swp);
108 
109  return 1;
110 }
111 
112 
113 /*
114  * This routine is called if setup fails (which it never should).
115  */
116 HIDDEN void
117 sh_null_print(register struct region *rp, void *UNUSED(dp))
118 {
119  bu_log("%s uses the null shader\n", rp->reg_name);
120 }
121 
122 
123 /*
124  * This routine is called after all rendering has completed. The intent is
125  * normally to release any specific structures that were allocated during
126  * setup or rendering.
127  *
128  * The null shader allocates nothing. Therefore it releases nothing.
129  */
130 HIDDEN void
132 {
133 }
134 
135 
136 /*
137  * Local Variables:
138  * mode: C
139  * tab-width: 8
140  * indent-tabs-mode: t
141  * c-file-style: "stroustrup"
142  * End:
143  * ex: shiftwidth=4 tabstop=8
144  */
void bu_log(const char *,...) _BU_ATTR_PRINTF12
Definition: log.c:176
#define MF_MAGIC
Definition: magic.h:205
Header file for the BRL-CAD common definitions.
const char * reg_name
Identifying string.
Definition: raytrace.h:539
#define HIDDEN
Definition: common.h:86
#define RT_AP_CHECK(_ap)
Definition: raytrace.h:1685
HIDDEN int sh_null_render(struct application *ap, const struct partition *pp, struct shadework *swp, void *dp)
Definition: sh_null.c:91
HIDDEN void sh_null_free(void *cp)
Definition: sh_null.c:131
HIDDEN int sh_null_setup(register struct region *rp, struct bu_vls *matparm, void **dpp, const struct mfuncs *mfp, struct rt_i *rtip)
Definition: sh_null.c:68
#define UNUSED(parameter)
Definition: common.h:239
HIDDEN void sh_null_print(register struct region *rp, void *dp)
Definition: sh_null.c:117
int rr_render(struct application *app, const struct partition *pp, struct shadework *swp)
#define RT_CHECK_PT(_p)
compat
Definition: raytrace.h:588
Definition: vls.h:56
Header file for the BRL-CAD Optical Library, LIBOPTICAL.
struct mfuncs null_mfuncs[]
Definition: sh_null.c:48