Rendering Scenes and Settings

Functions related to Photorendering. More...

Classes
struct	API_PhotoRenderPars
	Parameters for saving photo rendered picture into an image file. More...
struct	API_RendEffects
	The representation of the Rendering Settings / Effects tab page. More...
struct	API_RendImage
	The representation of the Rendering Settings / Size Background tab page. More...

Enumerations
enum	API_RendSetTypeID { APIRendSet_EffectsID , APIRendSet_ImageID }
	The enumeration of the available photorendering tab page types. More...

Functions
GSErrCode __ACENV_CALL	ACAPI_Rendering_PhotoRender (const API_PhotoRenderPars *photoRenderPars, const API_PrintPars *printPars=nullptr)
	Creates a photorealistic image of the 3D window.
GSErrCode __ACENV_CALL	ACAPI_Rendering_GetRenderingSets (void *rendInfo, API_RendSetTypeID rendSetType, const GS::UniString *sceneName=nullptr)
	Returns information on the photorendering settings.
GSErrCode __ACENV_CALL	ACAPI_Rendering_ChangeRenderingSets (void *rendEffects, API_RendSetTypeID rendSetType)
	Changes the photorendering settings.
GSErrCode __ACENV_CALL	ACAPI_Rendering_GetRenderingSceneNames (GS::Array< GS::UniString > *sceneNames)
	Returns the names of all the named Rendering Scenes.
GSErrCode __ACENV_CALL	ACAPI_Rendering_SetCurrentRenderingScene (const GS::UniString *newCurrentSceneName)
	Sets the current Rendering Scene to the given named Rendering Scene.

Detailed Description

Functions related to Photorendering.

Enumeration Type Documentation

API_RendSetTypeID

enum API_RendSetTypeID

The enumeration of the available photorendering tab page types.

Remarks

Use this enum as a selector to the ACAPI_Rendering_GetRenderingSets and ACAPI_Rendering_ChangeRenderingSets environment functions to get data of the different tab pages of the "Rendering Settings..." dialog.

Function Documentation

ACAPI_Rendering_ChangeRenderingSets()

GSErrCode __ACENV_CALL ACAPI_Rendering_ChangeRenderingSets	(	void *	rendEffects,
		API_RendSetTypeID	rendSetType
	)

Changes the photorendering settings.

Parameters

rendEffects	[in] Data of a "PhotoRendering Settings..." tab page. The type depends on the prefsType parameter
rendSetType	[in] Type of the PhotoRendering Settings you want to modify

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - rendInfo is nullptr or rendSetType is invalid

Remarks

This function is used to modify the settings of the different tab pages of the "PhotoRendering Settings..." dialog. Usable structures of photorendering types (for rendInfo) are:

• API_RendEffects,
• API_RendImage, Note: the rendSetType should be passed as a value instead of a pointer; see the example below. If you pass a valid location in the bkgPictFile pointer of the API_RendImage parameter, and the referenced file does not belong to any currently loaded library, then the image file will be copied into the embedded library of the project. This also means that any subsequent modifications to the original image file will not affect the rendering backround picture until you remove it, and add it again to the library. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

API_RendEffects      rendEffects;
API_RendImage        rendImage;
GSErrCode            err;
 
BNZeroMemory (&rendEffects, sizeof (API_RendEffects));
err = ACAPI_Environment (APIEnv_GetRenderingSetsID, &rendEffects, (void *) (Int32) APIRendSet_EffectsID);
if (err == NoError) {
    rendEffects.useBkgAlpha = true;
    err = ACAPI_Environment (APIEnv_ChangeRenderingSetsID, &rendEffects, (void *) (Int32) APIRendSet_EffectsID);
}
 
BNZeroMemory (&rendImage, sizeof (API_RendImage));
err = ACAPI_Environment (APIEnv_GetRenderingSetsID, &rendImage, (void *) (Int32) APIRendSet_ImageID);
if (err == NoError) {
    rendImage.bkgSkyRGB.f_red   = 0.7;
    rendImage.bkgSkyRGB.f_green = 0.5;
    rendImage.bkgSkyRGB.f_blue  = 1.0;
    err = ACAPI_Environment (APIEnv_ChangeRenderingSetsID, &rendImage, (void *) (Int32) APIRendSet_ImageID);
}
delete rendImage.bkgPictFile;

ACAPI_Rendering_GetRenderingSceneNames()

GSErrCode __ACENV_CALL ACAPI_Rendering_GetRenderingSceneNames

(

GS::Array< GS::UniString > *

sceneNames

)

Returns the names of all the named Rendering Scenes.

Parameters

sceneNames

[out] Array of the names of all the named Rendering Scenes.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - sceneNames is nullptr.

Remarks

The names are returned in the order of recent usage, putting the most recent rendering scene first.

ACAPI_Rendering_GetRenderingSets()

GSErrCode __ACENV_CALL ACAPI_Rendering_GetRenderingSets	(	void *	rendInfo,
		API_RendSetTypeID	rendSetType,
		const GS::UniString *	sceneName = nullptr
	)

Returns information on the photorendering settings.

Parameters

rendInfo	[out] Data of a "PhotoRendering Settings..." tab page. The type depends on the prefsType parameter
rendSetType	[in] Type of the PhotoRendering Settings you want to get
sceneName	[in] The name of the Rendering Scene of which the settings you want to get. If nullptr, the settings of the current Scene will be returned.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - rendInfo is nullptr or rendSetType is invalid
• APIERR_BADNAME - The sceneName parameter was not nullptr, and no named Rendering Scene exists with this name.

Remarks

Many switches and values are returned which can be set in the different tab pages of the "PhotoRendering Settings..." dialog. Usable structures of photorendering types (for rendInfo) are:

• API_RendEffects,
• API_RendImage, Note: the rendSetType should be passed as a value instead of a pointer. Note: when you get an API_RendImage with this function, don't forget to free the allocated memory: delete rendInfo.bkgPictFile;. See an example of getting and modifying photorendering settings at the description of ACAPI_Rendering_ChangeRenderingSets.

ACAPI_Rendering_PhotoRender()

GSErrCode __ACENV_CALL ACAPI_Rendering_PhotoRender	(	const API_PhotoRenderPars *	photoRenderPars,
		const API_PrintPars *	printPars = nullptr
	)

Creates a photorealistic image of the 3D window.

Parameters

photoRenderPars	[in] Parameters for saving the photorendered picture into image file
printPars	[in] Printing options for producing printed output of the photorendered picture. Optional parameter, can be nullptr

Returns

• NoError - The function has completed with success.
• APIERR_BADDATABASE - The current database does not match the current window
• APIERR_BADPARS - Either the rendPars parameter is nullptr

Remarks

This function is used to generate the photorendered image of the current 3D window, and save the picture into an image file defined in rendPars. The picture window will be closed automatically before the function returns. You can also print the rendered picture to the default printer if the printPars parameter is not nullptr. If you need printed output only, set the fileTypeID field of rendPars to APIFType_None. The photorendering settings can be accessed with the ACAPI_Rendering_GetRenderingSets and ACAPI_Rendering_ChangeRenderingSets functions.

Example

API_PhotoRenderPars     rendPars;
IO::Location            fileLoc ("c:\\temp\\MyPicture.jpg");
GSErrCode               err;
 
if (fileLoc.Status () != NoError)
    return APIERR_GENERAL;
 
BNZeroMemory (&rendPars, sizeof (API_PhotoRenderPars));
rendPars.fileTypeID = APIFType_JPEGFile;
rendPars.file = &fileLoc;
 
#if defined (macintosh)
rendPars.colorDepth = ColorDepth_Million_Colors;
#endif
#if defined (WINDOWS)
rendPars.colorDepth = ColorDepth_24bit_TrueColor;
#endif
 
err = ACAPI_Automate (APIDo_PhotoRenderID, &rendPars, nullptr);

ACAPI_Rendering_SetCurrentRenderingScene()

GSErrCode __ACENV_CALL ACAPI_Rendering_SetCurrentRenderingScene

(

const GS::UniString *

newCurrentSceneName

)

Sets the current Rendering Scene to the given named Rendering Scene.

Parameters

newCurrentSceneName

[in] The name of the Rendering Scene, which you want to set as the current Scene.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - newCurrentSceneName is nullptr.
• APIERR_BADNAME - No named Rendering Scene exists with this name (newCurrentSceneName).
• APIERR_GENERAL - Could not set newCurrentSceneName as the current Scene.

Remarks

This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.