SceneConverter

Availability  LightWave® 6.0
Component  Layout
Header  lwscenecv.h

Scene converters load scene files written in formats other than LightWave®'s native format.

When the user selects a scene file to load, Layout first tries to load it directly as a LightWave® format file. If it can't, it passes the filename to each installed scene converter until one of them claims to recognize the file. The scene converter reads the file and rewrites it as a LightWave® scene file, passing the name of this temporary file back to Layout. After loading this file, Layout calls the scene converter's deleteTmp function to remove it.

Activation Function

   XCALL_( int ) MySceneConvert( int version, GlobalFunc *global,
      LWSceneConverter *local, void *serverData );

The local argument to a scene converter's activation function is an LWSceneConverter.

   typedef struct st_LWSceneConverter {
      const char *filename;
      LWError     readFailure;
      const char *tmpScene;
      void       (*deleteTmp) (const char *tmpScene);
   } LWSceneConverter;

filename

The name of the non-native scene file. This is the file to be converted.

readFailure

A one-line error message. Set this if you recognize the file format but can't read the file for some reason. If you don't recognize the format, leave this and the tmpScene and deleteTmp fields NULL. This tells Layout to submit the file to the next installed converter.

tmpScene

The filename of the temporary LightWave®-format scene file created by the scene converter. If you successfully create this temporary file, you should also provide a valid deleteTmp callback. If an error occurs during the conversion, you should remove the partially written temporary file, set tmpScene to NULL, and set the readFailure field to an error message. Since this tells Layout to stop trying to load the file, you should be careful to distinguish between files you don't recognize and those you do but which contain errors. If you're not sure, leave the readFailure field NULL so that other converters have a chance to try to load the file.

deleteTmp( filename )

A function you provide for removing the tmpScene file you create. Layout calls this after reading the tmpScene file.

Example

Most scene converters will follow the pattern shown in this pseudocode. Note that rather than write our own deleteTmp function for removing the temporary LightWave® scene file, we just pass back the C runtime remove function.

   #include <lwserver.h>
   #include <lwscenecv.h>
   #include <stdio.h>
   #include <stdlib.h>

   XCALL_( int )
   MySceneConvert( int version, GlobalFunc *global,
      LWSceneConverter *local, void *serverData )
   {
      static char tempfile[ 260 ];
      FILE *ifp, *ofp;
   
      ifp = fopen( local->filename, "rb" );
      if ( !ifp ) return AFUNC_BADLOCAL;
   
      ... read some of the file ...
   
      if ( not our format )
         return AFUNC_OK;
   
      ofp = fopen( tempfile, "w" );
      if ( !ofp ) {
         fclose( ifp );
         local->readFailure = "Couldn't create temp scene file.";
         return AFUNC_OK;
      }
   
      ... convert the scene ...
   
      if ( error while converting ) {
         fclose( ifp );
         fclose( ofp );
         local->readFailure = "Error while converting.";
         return AFUNC_OK;
      }
   
      /* successful */
   
      local->tmpScene = tempfile;
      local->deleteTemp = remove;
      return AFUNC_OK;
   }

   ServerRecord ServerDesc[] = {
      { LWSCENECONVERTER_CLASS, "MySceneConverter", MySceneConvert },
      { NULL }
   };