Provides immersive material types and API declarations for ArkUI on the native side, to implement immersive UI effects such as the blurred background in semi-transparent mode and light sensing interaction feedback.
File to include: <arkui/native_material.h>
Library: libace_ndk.z.so
System capability: SystemCapability.ArkUI.ArkUI.Full
Related module: ArkUI_NativeModule
Since: 26.0.0
| Name | typedef Keyword | Description |
|---|---|---|
| ArkUI_ImmersiveStyle | ArkUI_ImmersiveStyle | Enumerates immersive material styles. The value range is defined in ArkUI_ImmersiveStyle. Invalid input of a style will cause creation to fail and return NULL. Different styles correspond to different material parameters, affecting the thickness and transparency of the material. |
| ArkUI_MaterialLevel | ArkUI_MaterialLevel | Enumerates material levels, which are related to device computing power levels. You can use OH_ArkUI_NativeModule_GetGlobalMaterialLevel to obtain the material level of the current device. |
| Name | typedef Keyword | Description |
|---|---|---|
| ArkUI_ImmersiveMaterial | ArkUI_ImmersiveMaterial | Defines an immersive material object on the native side. Immersive materials are classified into different levels based on device computing power. A material level is defined by ArkUI_MaterialLevel and can be obtained through OH_ArkUI_NativeModule_GetGlobalMaterialLevel. On devices with high- and mid-level computing power, the filter and shadow (NODE_SHADOW or NODE_CUSTOM_SHADOW) of the material layer are affected. On devices with low computing power, the background color (NODE_BACKGROUND_COLOR), border color (NODE_BORDER_COLOR), border width (NODE_BORDER_WIDTH), and shadow (NODE_SHADOW or NODE_CUSTOM_SHADOW) are affected. |
| ArkUI_ImmersiveMaterial* | ArkUI_ImmersiveMaterialHandle | Defines the pointer to an immersive material object. The immersive material is used to implement immersive visual effects. An immersive material object can be created by OH_ArkUI_NativeModule_ImmersiveMaterial_Create. The immersive material object can be destroyed by OH_ArkUI_NativeModule_ImmersiveMaterial_Destroy. The immersive material object to be destroyed must be a valid object created by OH_ArkUI_NativeModule_ImmersiveMaterial_Create. |
| ArkUI_LightEffectOptions | ArkUI_LightEffectOptions | Defines a light sensing interaction effect configuration object for immersive materials, which is used to configure the light sensing response effect generated when the immersive material interacts with users. After creation, the configuration object must be set to the immersive material object through OH_ArkUI_NativeModule_ImmersiveMaterial_SetLightEffect to take effect. By default, the light sensing interaction color is white (0xffffffff) during creation. |
| ArkUI_LightEffectOptions* | ArkUI_LightEffectOptionsHandle | Defines the pointer to a light sensing interaction effect configuration object. You can configure and manage the light sensing interaction effect parameters of the immersive material through this pointer. A light sensing interaction effect configuration object can be created by OH_ArkUI_NativeModule_LightEffectOptions_Create. The light sensing interaction effect configuration object can be destroyed by OH_ArkUI_NativeModule_LightEffectOptions_Destroy. The light sensing interaction effect configuration object to be destroyed must be a valid object created by OH_ArkUI_NativeModule_LightEffectOptions_Create. |
| Name | typedef Keyword | Description |
|---|---|---|
| bool OH_ArkUI_NativeModule_GetSystemMaterialSupported() | - | Checks whether the current device supports system materials (that is, the built-in material rendering capability of the device system). If true is returned, the NODE_SYSTEM_MATERIAL attribute can be used. Otherwise, setting this attribute will not take effect. This configuration item is defined by the device and cannot be modified. |
| ArkUI_MaterialLevel OH_ArkUI_NativeModule_GetGlobalMaterialLevel() | - | Obtains the global material level, which is related to the device computing power. This configuration item is defined by the device and cannot be modified. |
| ArkUI_ImmersiveMaterialHandle OH_ArkUI_NativeModule_ImmersiveMaterial_Create(ArkUI_ImmersiveStyle style) | - | Creates an immersive material object with a specified style. The material level of the created object follows the global material level, which can be obtained through OH_ArkUI_NativeModule_GetGlobalMaterialLevel. It is recommended to call OH_ArkUI_NativeModule_GetSystemMaterialSupported first to check whether the device supports system materials. If the device does not support system materials, setting the material through the NODE_SYSTEM_MATERIAL attribute will have no effect. |
| void OH_ArkUI_NativeModule_ImmersiveMaterial_Destroy(ArkUI_ImmersiveMaterialHandle material) | - | Destroys the immersive material object. |
| ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_SetStyle(ArkUI_ImmersiveMaterialHandle material, ArkUI_ImmersiveStyle style) | - | Sets a style for an immersive material object. This attribute is valid only for display effects of devices with high- and mid-level computing power. It does not take effect for devices with low-level computing power, but no error is reported. On devices with low-level computing power, the material affects attributes such as the background color and border, which are not controlled by the style parameters. |
| ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_GetStyle(ArkUI_ImmersiveMaterialHandle material, ArkUI_ImmersiveStyle* style) | - | Obtains the style of an immersive material object. |
| ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_SetMaterialColor(ArkUI_ImmersiveMaterialHandle material, uint32_t color) | - | Sets a material color for an immersive material object. This attribute is valid for the filter and shadow display effects on devices with all computing power levels. If not set, the default value 0 is used, indicating the transparent color. |
| ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_GetMaterialColor(ArkUI_ImmersiveMaterialHandle material, uint32_t* color) | - | Obtains the material color of an immersive material object. |
| ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_SetApplyShadow(ArkUI_ImmersiveMaterialHandle material, bool applyShadow) | - | Sets whether to apply a shadow to an immersive material object. This parameter takes effect for materials of all levels. If the value is true, the shadow effect in the material takes effect, which takes precedence over the common shadow attribute. It is applicable to the scenario where the shadow of the material is used. When the value is false, the common shadow attribute takes effect, and the material has no shadow effect. It is applicable to the scenario where the custom shadow effect needs to be used to replace the material shadow. If this parameter is not set, the default value true is used. |
| ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_GetApplyShadow(ArkUI_ImmersiveMaterialHandle material, bool* applyShadow) | - | Obtains whether a shadow is applied to an immersive material object. If this attribute has never been explicitly set, the default value true is returned. |
| ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_SetInteractive(ArkUI_ImmersiveMaterialHandle material, bool interactive) | - | Sets whether an immersive material object can be interactively deformed. This parameter takes effect for materials of all levels. If this parameter is set to true, the material can be interactively deformed. If this parameter is set to false, the material cannot be interactively deformed. If this parameter is not set, the component behavior is followed. |
| ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_GetInteractive(ArkUI_ImmersiveMaterialHandle material, bool* interactive) | - | Obtains whether an immersive material object can be interactively deformed. If this attribute has never been set, call OH_ArkUI_NativeModule_ImmersiveMaterial_SetInteractive first to set this attribute before obtaining it. Otherwise, the API returns ARKUI_ERROR_CODE_PARAM_ERROR. |
| ArkUI_LightEffectOptionsHandle OH_ArkUI_NativeModule_LightEffectOptions_Create() | - | Creates a light sensing interaction effect configuration object, which is used to configure the effect of highlighted feedback upon touch for an immersive material. The default color is white (0xffffffff). |
| void OH_ArkUI_NativeModule_LightEffectOptions_Destroy(ArkUI_LightEffectOptionsHandle options) | - | Destroys the light sensing interaction effect configuration object. |
| ArkUI_ErrorCode OH_ArkUI_NativeModule_LightEffectOptions_SetColor(ArkUI_LightEffectOptionsHandle options, uint32_t color) | - | Sets a color for the light sensing interaction effect. If this parameter is not set, the default color is white (0xffffffff). |
| ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_SetLightEffect(ArkUI_ImmersiveMaterialHandle material, const ArkUI_LightEffectOptionsHandle options) | - | Sets the light sensing interaction effect for an immersive material object. This attribute takes effect for materials of all levels. If a null pointer is passed, the light sensing interaction effect is disabled. If a non-null pointer is passed, the light sensing interaction effect is enabled using the configuration parameters. A non-null pointer to the light sensing interaction effect configuration can be created through OH_ArkUI_NativeModule_LightEffectOptions_Create, and its color can be set through OH_ArkUI_NativeModule_LightEffectOptions_SetColor. If this API is not called, the light sensing interaction effect follows the component's behavior. |
| ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_GetLightEffectColor(ArkUI_ImmersiveMaterialHandle material, uint32_t* color) | - | Obtains the color of the light sensing interaction effect for an immersive material object. This API can successfully obtain the color value only after OH_ArkUI_NativeModule_ImmersiveMaterial_SetLightEffect is called to set a non-null pointer to the light sensing interaction effect. If the light sensing interaction effect has never been set or has been disabled (by passing a null pointer to the light sensing interaction effect configuration), ARKUI_ERROR_CODE_PARAM_ERROR will be returned. |
enum ArkUI_ImmersiveStyle
Enumerates immersive material styles. Different styles correspond to different material parameters, which affect material thickness.
Since: 26.0.0
| Enum Item | Description |
|---|---|
| ARKUI_IMMERSIVE_STYLE_ULTRA_THIN = 0 | Ultra-thin style, which provides a very strong transparent effect. |
| ARKUI_IMMERSIVE_STYLE_THIN = 1 | Thin style, which provides a strong transparent effect. |
| ARKUI_IMMERSIVE_STYLE_REGULAR = 2 | Regular style, which provides a balanced visual effect. |
| ARKUI_IMMERSIVE_STYLE_THICK = 3 | Thick style, which provides a strong blur effect. |
| ARKUI_IMMERSIVE_STYLE_ULTRA_THICK = 4 | Ultra-thick style, which provides an extremely strong blur effect. |
enum ArkUI_MaterialLevel
Enumerates material levels, which are related to device computing power levels.
You can use OH_ArkUI_NativeModule_GetGlobalMaterialLevel to obtain the material level of the current device.
Since: 26.0.0
| Enum Item | Description |
|---|---|
| ARKUI_MATERIAL_LEVEL_EXQUISITE = 0 | Material level of devices with high-level computing power. |
| ARKUI_MATERIAL_LEVEL_GENTLE = 1 | Material level of devices with mid-level computing power. |
| ARKUI_MATERIAL_LEVEL_SMOOTH = 2 | Material level of devices with low-level computing power. |
bool OH_ArkUI_NativeModule_GetSystemMaterialSupported()
Description
Checks whether the current device supports system materials (that is, the built-in material rendering capability of the device system).
If true is returned, the NODE_SYSTEM_MATERIAL attribute can be used. Otherwise, setting this attribute will not take effect. This configuration item is defined by the device and cannot be modified.
Since: 26.0.0
Returns
| Type | Description |
|---|---|
| bool | Whether the current device supports system materials. The value true indicates that the current device supports system materials, and false indicates the opposite. |
ArkUI_MaterialLevel OH_ArkUI_NativeModule_GetGlobalMaterialLevel()
Description
Obtains the global material level, which is related to the device computing power. This configuration item is defined by the device and cannot be modified.
Since: 26.0.0
Returns
| Type | Description |
|---|---|
| ArkUI_MaterialLevel | Material level of the device. ARKUI_MATERIAL_LEVEL_EXQUISITE (0): material level for devices with high-level computing power. ARKUI_MATERIAL_LEVEL_GENTLE (1): material level for devices with medium-level computing power. ARKUI_MATERIAL_LEVEL_SMOOTH (2): material level for devices with low-level computing power. |
ArkUI_ImmersiveMaterialHandle OH_ArkUI_NativeModule_ImmersiveMaterial_Create(ArkUI_ImmersiveStyle style)
Description
Creates an immersive material object with a specified style. The material level of the created object follows the global material level, which can be obtained through OH_ArkUI_NativeModule_GetGlobalMaterialLevel.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| ArkUI_ImmersiveStyle style | Material style. Passing an invalid style will cause the setting failure, and the error code ARKUI_ERROR_CODE_PARAM_INVALID will be returned. This style is effective only for the display effect on devices with high- and mid-level computing power, and has no effect on devices with low-level computing power but no error will be reported. |
Returns
| Type | Description |
|---|---|
| ArkUI_ImmersiveMaterialHandle | Pointer to the created immersive material object. If the creation fails or the material style is invalid, null is returned. The returned object must be released by calling OH_ArkUI_NativeModule_ImmersiveMaterial_Destroy after being used. |
void OH_ArkUI_NativeModule_ImmersiveMaterial_Destroy(ArkUI_ImmersiveMaterialHandle material)
Description
Destroys the immersive material object.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| ArkUI_ImmersiveMaterialHandle material | Pointer to the immersive material object. |
ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_SetStyle(ArkUI_ImmersiveMaterialHandle material, ArkUI_ImmersiveStyle style)
Description
Sets a style for an immersive material object. This attribute is valid only for display effects of devices with high- and mid-level computing power. It does not take effect for devices with low-level computing power, but no error is reported. You can call OH_ArkUI_NativeModule_GetGlobalMaterialLevel to obtain the material level of the current device to determine whether this attribute takes effect.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| ArkUI_ImmersiveMaterialHandle material | Pointer to the immersive material object. If material is NULL, the API returns the error code ARKUI_ERROR_CODE_PARAM_INVALID. |
| ArkUI_ImmersiveStyle style | Material style. Passing an invalid style will cause the setting failure, and the error code ARKUI_ERROR_CODE_PARAM_INVALID will be returned. |
Returns
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs (material is NULL or style is invalid). Ensure that a valid material pointer and a valid style enumerated value are passed. |
ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_GetStyle(ArkUI_ImmersiveMaterialHandle material, ArkUI_ImmersiveStyle* style)
Description
Obtains the style of an immersive material object.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| ArkUI_ImmersiveMaterialHandle material | Pointer to the immersive material object. |
| ArkUI_ImmersiveStyle style | Pointer to the variable used to receive the material style. |
Returns
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs (material or style is NULL). Ensure that both material and style are valid pointers. |
ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_SetMaterialColor(ArkUI_ImmersiveMaterialHandle material, uint32_t color)
Description
Sets a material color for an immersive material object. This attribute is valid for the display effects on devices with all computing power levels. You can call OH_ArkUI_NativeModule_GetGlobalMaterialLevel to obtain the material level of the current device to determine whether this attribute takes effect. If this parameter is not set, the default value 0 is used, indicating the transparent color.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| ArkUI_ImmersiveMaterialHandle material | Pointer to the immersive material object. If material is NULL, the API returns the error code ARKUI_ERROR_CODE_PARAM_INVALID. |
| uint32_t color | Material color, in 0xAARRGGBB format, which takes effect on the display effects of devices with all computing power levels. The value 0 indicates transparent (default value). |
Returns
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs (material is NULL). Ensure that material is a valid pointer. |
ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_GetMaterialColor(ArkUI_ImmersiveMaterialHandle material, uint32_t* color)
Description
Obtains the material color of an immersive material object.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| ArkUI_ImmersiveMaterialHandle material | Pointer to the immersive material object. |
| uint32_t* color | Pointer to the variable used to receive the material color in 0xAARRGGBB format. |
Returns
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs (material or color is NULL). Ensure that both material and color are valid pointers. |
ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_SetApplyShadow(ArkUI_ImmersiveMaterialHandle material, bool applyShadow)
Description
Sets whether to apply a shadow to an immersive material object. This parameter takes effect for materials of all levels.
If this parameter is set to true, the shadow effect in the material takes effect and takes precedence over the common shadow attribute. If this parameter is set to false, the common shadow attribute takes effect, and the material has no shadow effect. If this parameter is not set, the default value true is used.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| ArkUI_ImmersiveMaterialHandle material | Pointer to the immersive material object. |
| bool applyShadow | Whether to apply a shadow to the material. The value true indicates that the material shadow takes effect and takes precedence over the common shadow attribute. The value false indicates that the material shadow is not added and the common shadow attribute takes effect. The default value is true. |
Returns
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs (material is NULL). Ensure that material is a valid pointer. |
ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_GetApplyShadow(ArkUI_ImmersiveMaterialHandle material, bool* applyShadow)
Description
Obtains whether a shadow is applied to an immersive material object.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| ArkUI_ImmersiveMaterialHandle material | Pointer to the immersive material object. |
| bool* applyShadow | Pointer to the variable used to receive whether the shadow is applied. If never explicitly set, this pointer receives the default value true. |
Returns
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs (material or applyShadow is NULL). Ensure that both material and applyShadow are valid pointers. |
ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_SetInteractive(ArkUI_ImmersiveMaterialHandle material, bool interactive)
Description
Sets whether an immersive material object can be interactively deformed. That is, whether the material generates a visual deformation response during user interaction (such as touch and press). This parameter takes effect for materials of all levels.
If this parameter is set to true, the material can be interactively deformed. If this parameter is set to false, the material cannot be interactively deformed. If this parameter is not set, the component behavior is followed.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| ArkUI_ImmersiveMaterialHandle material | Pointer to the immersive material object. |
| bool interactive | Whether interactive deformation can be performed for a material. The value true indicates that interactive deformation can be performed for a material, and false indicates the opposite. If this parameter is not set, the component behavior is followed. |
Returns
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs (material is NULL). Ensure that material is a valid pointer. |
ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_GetInteractive(ArkUI_ImmersiveMaterialHandle material, bool* interactive)
Description
Obtains whether an immersive material object can be interactively deformed. You are advised to call OH_ArkUI_NativeModule_ImmersiveMaterial_SetInteractive to set this attribute before calling this API. If this attribute has never been set, ARKUI_ERROR_CODE_PARAM_ERROR will be returned.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| ArkUI_ImmersiveMaterialHandle material | Pointer to the immersive material object. If material is NULL, the API returns the error code ARKUI_ERROR_CODE_PARAM_INVALID. |
| bool* interactive | Pointer to the variable used to receive whether the material supports interactive deformation. If interactive is NULL, the API returns the error code ARKUI_ERROR_CODE_PARAM_INVALID. |
Returns
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs (material or interactive is NULL). Ensure that both material and interactive are valid pointers. Returns ARKUI_ERROR_CODE_PARAM_ERROR if this attribute has never been set. Call OH_ArkUI_NativeModule_ImmersiveMaterial_SetInteractive to set this attribute before obtaining it. |
ArkUI_LightEffectOptionsHandle OH_ArkUI_NativeModule_LightEffectOptions_Create()
Description
Creates a light sensing interaction effect configuration object, which is used to configure the effect of highlighted feedback upon touch for an immersive material. The default color is white (0xffffffff). After the creation is complete, you need to call OH_ArkUI_NativeModule_ImmersiveMaterial_SetLightEffect to set the configuration object to the immersive material object for the configuration to take effect.
Since: 26.0.0
Returns
| Type | Description |
|---|---|
| ArkUI_LightEffectOptionsHandle | Pointer to the created light sensing interaction effect configuration object. The returned object must be released by calling OH_ArkUI_NativeModule_LightEffectOptions_Destroy after being used. |
void OH_ArkUI_NativeModule_LightEffectOptions_Destroy(ArkUI_LightEffectOptionsHandle options)
Description
Destroys the light sensing interaction effect configuration object.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| ArkUI_LightEffectOptionsHandle options | Pointer to the light sensing interaction effect configuration object. |
ArkUI_ErrorCode OH_ArkUI_NativeModule_LightEffectOptions_SetColor(ArkUI_LightEffectOptionsHandle options, uint32_t color)
Description
Sets a color for the light sensing interaction effect. If this parameter is not set, the default color is white (0xffffffff).
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| ArkUI_LightEffectOptionsHandle options | Pointer to the light sensing interaction effect configuration object. |
| uint32_t color | Color of the light sensing interaction effect, in 0xAARRGGBB format. If this parameter is not set, the default color is white (0xffffffff). |
Returns
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs (options is NULL). Ensure that options is a valid pointer. |
ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_SetLightEffect(ArkUI_ImmersiveMaterialHandle material, const ArkUI_LightEffectOptionsHandle options)
Description
Sets the light sensing interaction effect for an immersive material object, that is, the light reflection on the material surface that dynamically changes with user interaction. This parameter takes effect for materials of all levels.
If a null pointer is passed, the light sensing interaction effect is disabled, which applies to scenarios of purely presentational material surfaces. If a non-null pointer is passed, the light sensing interaction effect is enabled using the configuration parameters, which applies to scenarios of interactive components that require enhanced touch and visual feedback. If this API is not called, the light sensing interaction effect follows the component's behavior.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| ArkUI_ImmersiveMaterialHandle material | Pointer to the immersive material object. |
| const ArkUI_LightEffectOptionsHandle options | Pointer to the light sensing interaction effect configuration object. A null pointer disables the light sensing interaction effect, and a non-null enables it. A non-null pointer must be created through OH_ArkUI_NativeModule_LightEffectOptions_Create. |
Returns
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs (material is NULL). Ensure that material is a valid pointer. |
ArkUI_ErrorCode OH_ArkUI_NativeModule_ImmersiveMaterial_GetLightEffectColor(ArkUI_ImmersiveMaterialHandle material, uint32_t* color)
Description
Obtains the color of the light sensing interaction effect for an immersive material object.
This API can successfully obtain the color value only after OH_ArkUI_NativeModule_ImmersiveMaterial_SetLightEffect is called to set a non-null pointer to the light sensing interaction effect. If the light sensing interaction effect has never been set or has been disabled (by passing a null pointer to the light sensing interaction effect configuration), ARKUI_ERROR_CODE_PARAM_ERROR will be returned.
Since: 26.0.0
Parameters
| Name | Description |
|---|---|
| ArkUI_ImmersiveMaterialHandle material | Pointer to the immersive material object. |
| uint32_t* color | Pointer to the variable used to receive the light sensing interaction effect color in 0xAARRGGBB format. |
Returns
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs (material or color is NULL). Ensure that both material and color are valid pointers. Returns ARKUI_ERROR_CODE_PARAM_ERROR if the light sensing interaction effect has never been set or has been disabled. Call OH_ArkUI_NativeModule_ImmersiveMaterial_SetLightEffect first to set a non-null light sensing interaction effect configuration pointer before obtaining the color. |