Luigi Castelli

in jgraphics.h there are two functions prototyped as such:

/**    Create an image surface, filling it with the contents of a file, and get a reference to the surface.
    Use jgraphics_surface_destroy() to release your reference to the surface when you are done.
    @ingroup            jsurface
    @param    filename    The name of the file.
    @param    path        The path id of the file.
    @return                A pointer to the new surface.        */
t_jsurface *jgraphics_image_surface_create_referenced(const char *filename, short path);

/**    Create an image surface, filling it with the contents of a file.
    Use jgraphics_surface_destroy() to free it when you are done.
    @ingroup            jsurface
    @param    filename    The name of the file.
    @param    path        The path id of the file.
    @return                A pointer to the new surface.        */
t_jsurface* jgraphics_image_surface_create_from_file(const char *filename, short path);

They are used when loading a surface previously saved on disk.

In my experience they both work pretty much in the same fashion.

Is there any significant difference between the two ?

In what situations is one to be preferred over the other ?

/**	Create an image surface, filling it with the contents of a file, and get a reference to the surface.
	Use jgraphics_surface_destroy() to release your reference to the surface when you are done.
	@ingroup			jsurface
	@param	filename	The name of the file.
	@param	path		The path id of the file.
	@return				A pointer to the new surface.		*/
t_jsurface *jgraphics_image_surface_create_referenced(const char *filename, short path);

/**	Create an image surface, filling it with the contents of a file.
	Use jgraphics_surface_destroy() to free it when you are done.
	@ingroup			jsurface
	@param	filename	The name of the file.
	@param	path		The path id of the file.
	@return				A pointer to the new surface.		*/
t_jsurface* jgraphics_image_surface_create_from_file(const char *filename, short path);

They are used when loading a surface previously saved on disk.
In my experience they both work pretty much in the same fashion.

Is there any significant difference between the two ?
In what situations is one to be preferred over the other ?

surface_create_referenced-vs-surface_create_from_file

jgraphics_image_surface_create_referenced() Loads once for the file and caches in a hashtable for objects to share. Best for use when loading a file into an image surface that will be used by multiple objects.

surface_create_referenced VS surface_create_from_file