Modify External Renderer: External renderer docu updated for future changes, restructuring. Not that the changes in the documentation are not yet implemented in code

doxygen/external-renderer.dox

@@ -12,4 +12,14 @@
  *
  * All these properties have to be set for rendering.
  *
+ * @section ExternalRendererFuncs Necessary Functions
+ *
+ * The following functions and variables are necessary for an external renderer to implement:
+ *
+ * Code Define 				| Prototype  																	|  Description
+ * ---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------
+ * @ref EXTERNAL_LIBRARY_RENDER_FUNCTION	| int EXTERNAL_LIBRARY_RENDER_FUNCTION(struct gds_cell *toplevel, GList *layer_info_list, const char *output_file_name, double scale)		| Render cell to output file
+ * @ref EXTERNAL_LIBRARY_INIT_FUNCTION		| int EXTERNAL_LIBRARY_INIT_FUNCTION(const char *option_string, const char *version_string)							| Init function. Executed before rendering. This is given the command line parameters specified for the external renderer and the version string of the currently running gds-render program.
+ * @ref EXTERNAL_LIBRARY_FORK_REQUEST		| int EXTERNAL_LIBRARY_FORK_REQUEST;														| The pure presence of this integer results in the execution inside a subprocess of hte whole shared object's code
+ *
  */

include/gds-render/output-renderers/external-renderer-interfaces.h

@@ -0,0 +1,46 @@
+#ifndef __EXTERNAL_RENDERER_INTERFACES_H__
+#define __EXTERNAL_RENDERER_INTERFACES_H__
+
+#ifndef xstr
+
+#define xstr(a) str(a)
+#define str(a) #a
+
+#endif /* xstr */
+
+/**
+ * @addtogroup ExternalRenderer
+ * @{
+ */
+
+/**
+ * @brief Function name expected to be found in external library for rendering.
+ *
+ * The function has to be defined as follows:
+ * @code
+ * int EXTERNAL_LIBRARY_RENDER_FUNCTION(struct gds_cell *toplevel, GList *layer_info_list, const char *output_file_name, double scale);
+ * @endcode
+ */
+#define EXTERNAL_LIBRARY_RENDER_FUNCTION exported_render_cell_to_file
+
+/**
+ * @brief Function name expected to be found in external library for initialization.
+ *
+ * @code
+ * int EXTERNAL_LIBRARY_INIT_FUNCTION(const char *option_string, const char *version_string);
+ * @endcode
+ */
+#define EXTERNAL_LIBRARY_INIT_FUNCTION exported_init
+
+/**
+ * @brief Global integer specified by an external renderer to signal, that the init and render functions shall be executed in a subprocess
+ *
+ * The pure presence of this symbol name causes forking. The content of this variable is don't care.
+ * @note Use this if you mess with the internal structures of gds-render
+ *
+ */
+#define EXTERNAL_LIBRARY_FORK_REQUEST exported_fork_request
+
+/** @} */
+
+#endif /* __EXTERNAL_RENDERER_INTERFACES_H__ */

include/gds-render/output-renderers/external-renderer.h

@@ -33,6 +33,7 @@
 
 #include <gds-render/output-renderers/gds-output-renderer.h>
 #include <gds-render/gds-utils/gds-types.h>
+#include <gds-render/output-renderers/external-renderer-interfaces.h>
 
 G_BEGIN_DECLS
 
@@ -40,16 +41,6 @@ G_BEGIN_DECLS
 
 G_DECLARE_FINAL_TYPE(ExternalRenderer, external_renderer, GDS_RENDER, EXTERNAL_RENDERER, GdsOutputRenderer)
 
-/**
- * @brief function name expected to be found in external library.
- * 
- * The function has to be defined as follows:
- * @code
- * int EXTERNAL_LIBRARY_FUNCTION(struct gds_cell *toplevel, GList *layer_info_list, const char *output_file_name, double scale)
- * @endcode
- */
-#define EXTERNAL_LIBRARY_FUNCTION "render_cell_to_file"
-
 /**
  * @brief Create new ExternalRenderer object
  * @return New object

main.c

@@ -285,7 +285,7 @@ int main(int argc, char **argv)
 		{"tex-standalone", 'a', 0, G_OPTION_ARG_NONE, &pdf_standalone, _("Create standalone TeX"), NULL },
 		{"tex-layers", 'l', 0, G_OPTION_ARG_NONE, &pdf_layers, _("Create PDF Layers (OCG)"), NULL },
 		{"custom-render-lib", 'P', 0, G_OPTION_ARG_FILENAME, &custom_library_path, 
-			"Path to a custom shared object, that implements the " EXTERNAL_LIBRARY_FUNCTION " function", "PATH"},
+			"Path to a custom shared object, that implements the necessary rendering functions", "PATH"},
 		{NULL}
 	};
 

output-renderers/external-renderer.c

@@ -80,7 +80,7 @@ static int external_renderer_render_cell(struct gds_cell *toplevel_cell, GList *
 
 	/* Load symbol from library */
 	so_render_func = (int (*)(struct gds_cell *, GList *, const char *, double))
-				dlsym(so_handle, EXTERNAL_LIBRARY_FUNCTION);
+				dlsym(so_handle, xstr(EXTERNAL_LIBRARY_RENDER_FUNCTION));
 	error_msg = dlerror();
 	if (error_msg != NULL) {
 		fprintf(stderr, "Rendering function not found in library:\n%s\n", error_msg);