From 49ff4974eaa9b3a5f2eccbfda2bb2315b8ead32c Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Fri, 5 Sep 2014 00:24:04 +0200 Subject: add documation to .c files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- src/libgamma_AdjustmentMethod.c | 50 +++++++++++++ src/libgamma_CRTC.c | 147 ++++++++++++++++++++++++++++++++++++++ src/libgamma_GammaRamps.c | 149 +++++++++++++++++++++++++++++++++++++++ src/libgamma_LibgammaException.c | 40 +++++++++++ src/libgamma_Partition.c | 25 +++++++ src/libgamma_Ramp.c | 107 ++++++++++++++++++++++++++++ src/libgamma_Site.c | 25 +++++++ 7 files changed, 543 insertions(+) diff --git a/src/libgamma_AdjustmentMethod.c b/src/libgamma_AdjustmentMethod.c index dc247a9..c8d9e4e 100644 --- a/src/libgamma_AdjustmentMethod.c +++ b/src/libgamma_AdjustmentMethod.c @@ -18,9 +18,59 @@ #include "libgamma_AdjustmentMethod.h" +/** + * List available adjustment methods by their order of preference based on the environment. + * + * @param operation Allowed values: + * 0: Methods that the environment suggests will work, excluding fake. + * 1: Methods that the environment suggests will work, including fake. + * 2: All real non-fake methods. + * 3: All real methods. + * 4: All methods. + * Other values invoke undefined behaviour. + * @return List available adjustment methods by their order of preference. + */ jintArray Java_libgamma_AdjustmentMethod_libgamma_1list_1methods(JNIEnv *, jclass, jint); + + +/** + * Check whether an adjustment method is available, non-existing (invalid) methods will be + * identified as not available under the rationale that the library may be out of date. + * + * @param method The adjustment method. + * @return Whether the adjustment method is available. + */ jint Java_libgamma_AdjustmentMethod_libgamma_1is_1method_1available(JNIEnv *, jclass, jint); + + + +/** + * Return the capabilities of an adjustment method. + * + * @param method The adjustment method (display server and protocol). + * @return Input parameter to the constructor of {@link AdjustmentMethodCapabilities}. + */ jlong Java_libgamma_AdjustmentMethod_libgamma_1method_1capabilities(JNIEnv *, jclass, jint); + + +/** + * Return the default site for an adjustment method. + * + * @param method The adjustment method (display server and protocol.) + * @return The default site, {@code null} if it cannot be determined or + * if multiple sites are not supported by the adjustment method. + */ jstring Java_libgamma_AdjustmentMethod_libgamma_1method_1default_1site(JNIEnv *, jclass, jint); + + +/** + * Return the default variable that determines + * the default site for an adjustment method. + * + * @param method The adjustment method (display server and protocol.) + * @return The environ variables that is used to determine the + * default site. {@code null} if there is none, that is, + * if the method does not support multiple sites. + */ jstring Java_libgamma_AdjustmentMethod_libgamma_1method_1default_1site_1variable(JNIEnv *, jclass, jint); diff --git a/src/libgamma_CRTC.c b/src/libgamma_CRTC.c index 1abf189..9d6958b 100644 --- a/src/libgamma_CRTC.c +++ b/src/libgamma_CRTC.c @@ -18,20 +18,167 @@ #include "libgamma_CRTC.h" +/** + * Create a CRTC state. + * + * @param partition The partition state for the partition that the CRTC belongs to. + * @param crtc The index of the CRTC within the partition. + * @return Element 0: The value for {@link #address}. + * Element 1: Error code, zero on success. + */ jlongArray Java_libgamma_CRTC_libgamma_1crtc_1create(JNIEnv *, jclass, jlong, jint); + + +/** + * Release all resources held by a CRTC state + * and free the CRTC state pointer. + * + * @param address The CRTC state. + */ void Java_libgamma_CRTC_libgamma_1crtc_1free(JNIEnv *, jclass, jlong); + + +/** + * Restore the gamma ramps for a CRTC to the system settings for that CRTC. + * + * @param address The CRTC state. + * @return Zero on success, and error code on failure. + */ jint Java_libgamma_CRTC_libgamma_1crtc_1restore(JNIEnv *, jclass, jlong); + + +/** + * Read information about a CRTC. + * + * @param crtc The state of the CRTC whose information should be read. + * @param fields OR:ed identifiers for the information about the CRTC that should be read. + * @return Input parameters for the constructor of {@link CRTCInformation} + */ jobjectArray Java_libgamma_CRTC_libgamma_1get_1crtc_1information(JNIEnv *, jclass, jlong, jint); + + + +/** + * Get the current gamma ramps for a CRTC, 8-bit gamma-depth version. + * + * @param address The CRTC state. + * @param ramps The gamma ramps to fill with the current values + * @return Zero on success, an error code on failure. + */ jint Java_libgamma_CRTC_libgamma_1crtc_1get_1gamma_1ramps8(JNIEnv *, jclass, jlong, jlong); + + +/** + * Set the gamma ramps for a CRTC, 8-bit gamma-depth version. + * + * @param address The CRTC state. + * @param ramps The gamma ramps to apply. + * @return Zero on success, an error code on failure. + */ jint Java_libgamma_CRTC_libgamma_1crtc_1set_1gamma_1ramps8(JNIEnv *, jclass, jlong, jlong); + + + +/** + * Get the current gamma ramps for a CRTC, 16-bit gamma-depth version. + * + * @param address The CRTC state. + * @param ramps The gamma ramps to fill with the current values + * @return Zero on success, an error code on failure. + */ jint Java_libgamma_CRTC_libgamma_1crtc_1get_1gamma_1ramps16(JNIEnv *, jclass, jlong, jlong); + + +/** + * Set the gamma ramps for a CRTC, 16-bit gamma-depth version. + * + * @param address The CRTC state. + * @param ramps The gamma ramps to apply. + * @return Zero on success, an error code on failure. + */ jint Java_libgamma_CRTC_libgamma_1crtc_1set_1gamma_1ramps16(JNIEnv *, jclass, jlong, jlong); + + + +/** + * Get the current gamma ramps for a CRTC, 32-bit gamma-depth version. + * + * @param address The CRTC state. + * @param ramps The gamma ramps to fill with the current values. + * @return Zero on success, an error code on failure. + */ jint Java_libgamma_CRTC_libgamma_1crtc_1get_1gamma_1ramps32(JNIEnv *, jclass, jlong, jlong); + + +/** + * Set the gamma ramps for a CRTC, 32-bit gamma-depth version. + * + * @param address The CRTC state. + * @param ramps The gamma ramps to apply. + * @return Zero on success, an error code on failure. + */ jint Java_libgamma_CRTC_libgamma_1crtc_1set_1gamma_1ramps32(JNIEnv *, jclass, jlong, jlong); + + + +/** + * Get the current gamma ramps for a CRTC, 64-bit gamma-depth version. + * + * @param address The CRTC state. + * @param ramps The gamma ramps to fill with the current values. + * @return Zero on success, an error code on failure. + */ jint Java_libgamma_CRTC_libgamma_1crtc_1get_1gamma_1ramps64(JNIEnv *, jclass, jlong, jlong); + + +/** + * Set the gamma ramps for a CRTC, 64-bit gamma-depth version. + * + * @param address The CRTC state. + * @param ramps The gamma ramps to apply. + * @return Zero on success, an error code on failure. + */ jint Java_libgamma_CRTC_libgamma_1crtc_1set_1gamma_1ramps64(JNIEnv *, jclass, jlong, jlong); + + + +/** + * Set the gamma ramps for a CRTC, single precision floating point version. + * + * @param address The CRTC state. + * @param ramps The gamma ramps to apply. + * @return Zero on success, an error code on failure. + */ jint Java_libgamma_CRTC_libgamma_1crtc_1set_1gamma_1rampsf(JNIEnv *, jclass, jlong, jlong); + + +/** + * Get the current gamma ramps for a CRTC, single precision floating point version. + * + * @param address The CRTC state. + * @param ramps The gamma ramps to fill with the current values. + * @return Zero on success, an error code on failure. + */ jint Java_libgamma_CRTC_libgamma_1crtc_1get_1gamma_1rampsf(JNIEnv *, jclass, jlong, jlong); + + + +/** + * Get the current gamma ramps for a CRTC, double precision floating point version. + * + * @param address The CRTC state. + * @param ramps The gamma ramps to fill with the current values. + * @return Zero on success, an error code on failure. + */ jint Java_libgamma_CRTC_libgamma_1crtc_1get_1gamma_1rampsd(JNIEnv *, jclass, jlong, jlong); + + +/** + * Set the gamma ramps for a CRTC, double precision floating point version. + * + * @param address The CRTC state. + * @param ramps The gamma ramps to apply. + * @return Zero on success, an error code on failure. + */ jint Java_libgamma_CRTC_libgamma_1crtc_1set_1gamma_1rampsd(JNIEnv *, jclass, jlong, jlong); diff --git a/src/libgamma_GammaRamps.c b/src/libgamma_GammaRamps.c index cae50fa..2a12e82 100644 --- a/src/libgamma_GammaRamps.c +++ b/src/libgamma_GammaRamps.c @@ -18,16 +18,165 @@ #include "libgamma_GammaRamps.h" +/** + * Create and initialise a gamma ramp in the proper way that allows all adjustment + * methods to read from and write to it without causing segmentation violation. + * + * @param red_size The size of the encoding axis of the red gamma ramp. + * @param green_size The size of the encoding axis of the green gamma ramp. + * @param blue_size The size of the encoding axis of the blue gamma ramp. + * @return Element 0: The address of the native object. + * Element 1: The address of the red gamma ramp. + * Element 2: The address of the green gamma ramp. + * Element 3: The address of the blue gamma ramp. + * Element 4: Zero on success, an error code on error. + */ jlongArray Java_libgamma_GammaRamps_libgamma_1gamma_1ramps8_1create(JNIEnv *, jclass, jint, jint, jint); + + +/** + * Create and initialise a gamma ramp in the proper way that allows all adjustment + * methods to read from and write to it without causing segmentation violation. + * + * @param red_size The size of the encoding axis of the red gamma ramp. + * @param green_size The size of the encoding axis of the green gamma ramp. + * @param blue_size The size of the encoding axis of the blue gamma ramp. + * @return Element 0: The address of the native object. + * Element 1: The address of the red gamma ramp. + * Element 2: The address of the green gamma ramp. + * Element 3: The address of the blue gamma ramp. + * Element 4: Zero on success, an error code on error. + */ jlongArray Java_libgamma_GammaRamps_libgamma_1gamma_1ramps16_1create(JNIEnv *, jclass, jint, jint, jint); + + +/** + * Create and initialise a gamma ramp in the proper way that allows all adjustment + * methods to read from and write to it without causing segmentation violation. + * + * @param red_size The size of the encoding axis of the red gamma ramp. + * @param green_size The size of the encoding axis of the green gamma ramp. + * @param blue_size The size of the encoding axis of the blue gamma ramp. + * @return Element 0: The address of the native object. + * Element 1: The address of the red gamma ramp. + * Element 2: The address of the green gamma ramp. + * Element 3: The address of the blue gamma ramp. + * Element 4: Zero on success, an error code on error. + */ jlongArray Java_libgamma_GammaRamps_libgamma_1gamma_1ramps32_1create(JNIEnv *, jclass, jint, jint, jint); + + +/** + * Create and initialise a gamma ramp in the proper way that allows all adjustment + * methods to read from and write to it without causing segmentation violation. + * + * @param red_size The size of the encoding axis of the red gamma ramp. + * @param green_size The size of the encoding axis of the green gamma ramp. + * @param blue_size The size of the encoding axis of the blue gamma ramp. + * @return Element 0: The address of the native object. + * Element 1: The address of the red gamma ramp. + * Element 2: The address of the green gamma ramp. + * Element 3: The address of the blue gamma ramp. + * Element 4: Zero on success, an error code on error. + */ jlongArray Java_libgamma_GammaRamps_libgamma_1gamma_1ramps64_1create(JNIEnv *, jclass, jint, jint, jint); + + +/** + * Create and initialise a gamma ramp in the proper way that allows all adjustment + * methods to read from and write to it without causing segmentation violation. + * + * @param red_size The size of the encoding axis of the red gamma ramp. + * @param green_size The size of the encoding axis of the green gamma ramp. + * @param blue_size The size of the encoding axis of the blue gamma ramp. + * @return Element 0: The address of the native object. + * Element 1: The address of the red gamma ramp. + * Element 2: The address of the green gamma ramp. + * Element 3: The address of the blue gamma ramp. + * Element 4: Zero on success, an error code on error. + */ jlongArray Java_libgamma_GammaRamps_libgamma_1gamma_1rampsf_1create(JNIEnv *, jclass, jint, jint, jint); + + +/** + * Create and initialise a gamma ramp in the proper way that allows all adjustment + * methods to read from and write to it without causing segmentation violation. + * + * @param red_size The size of the encoding axis of the red gamma ramp. + * @param green_size The size of the encoding axis of the green gamma ramp. + * @param blue_size The size of the encoding axis of the blue gamma ramp. + * @return Element 0: The address of the native object. + * Element 1: The address of the red gamma ramp. + * Element 2: The address of the green gamma ramp. + * Element 3: The address of the blue gamma ramp. + * Element 4: Zero on success, an error code on error. + */ jlongArray Java_libgamma_GammaRamps_libgamma_1gamma_1rampsd_1create(JNIEnv *, jclass, jint, jint, jint); + + + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by {@link #libgamma_gamma_ramps8_create} or + * otherwise initialised in the proper manner, as well as release + * the pointer to the structure. + * + * @param address The gamma ramps. + */ void Java_libgamma_GammaRamps_libgamma_1gamma_1ramps8_1free(JNIEnv *, jclass, jlong); + + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by {@link #libgamma_gamma_ramps16_create} or + * otherwise initialised in the proper manner, as well as release + * the pointer to the structure. + * + * @param address The gamma ramps. + */ void Java_libgamma_GammaRamps_libgamma_1gamma_1ramps16_1free(JNIEnv *, jclass, jlong); + + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by {@link #libgamma_gamma_ramps32_create} or + * otherwise initialised in the proper manner, as well as release + * the pointer to the structure. + * + * @param address The gamma ramps. + */ void Java_libgamma_GammaRamps_libgamma_1gamma_1ramps32_1free(JNIEnv *, jclass, jlong); + + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by {@link #libgamma_gamma_ramps64_create} or + * otherwise initialised in the proper manner, as well as release + * the pointer to the structure. + * + * @param address The gamma ramps. + */ void Java_libgamma_GammaRamps_libgamma_1gamma_1ramps64_1free(JNIEnv *, jclass, jlong); + + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by {@link #libgamma_gamma_rampsf_create} or + * otherwise initialised in the proper manner, as well as release + * the pointer to the structure. + * + * @param address The gamma ramps. + */ void Java_libgamma_GammaRamps_libgamma_1gamma_1rampsf_1free(JNIEnv *, jclass, jlong); + + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by {@link #libgamma_gamma_rampsd_create} or + * otherwise initialised in the proper manner, as well as release + * the pointer to the structure. + * + * @param address The gamma ramps. + */ void Java_libgamma_GammaRamps_libgamma_1gamma_1rampsd_1free(JNIEnv *, jclass, jlong); diff --git a/src/libgamma_LibgammaException.c b/src/libgamma_LibgammaException.c index a0d6f33..fac3e1c 100644 --- a/src/libgamma_LibgammaException.c +++ b/src/libgamma_LibgammaException.c @@ -18,9 +18,49 @@ #include "libgamma_LibgammaException.h" +/** + * Returns the name of the definition associated with + * a libgamma error code. + * + * @param value The error code. + * @return The name of the definition associated with the error code, + * {@code null} if the error code does not exist. + */ jstring Java_libgamma_LibgammaException_name_1of_1error(JNIEnv *, jclass, jint); + + +/** + * Return the value of a libgamma error definition + * refered to by name. + * + * @param name The name of the definition associated with the error code. + * @return The error code, zero if the name is {@code null} + * or does not refer to a libgamma error. + */ jint Java_libgamma_LibgammaException_value_1of_1error(JNIEnv *, jclass, jstring); + + +/** + * Acquire the value that should go to {@link #group_gid}. + * + * @return The value that should go to {@link #group_gid}. + */ jint Java_libgamma_LibgammaException_libgamma_1group_1gid(JNIEnv *, jclass); + + +/** + * Acquire the value that should go to {@link #group_name}. + * + * @return The value that should go to {@link #group_name}. + */ jstring Java_libgamma_LibgammaException_libgamma_1group_1name(JNIEnv *, jclass); + + +/** + * Get a textual description of a system error code. + * + * @param error_code The error code. + * @return A textual description of the error code. + */ jstring Java_libgamma_LibgammaException_strerror(JNIEnv *, jclass, jint); diff --git a/src/libgamma_Partition.c b/src/libgamma_Partition.c index 2228240..b7baebd 100644 --- a/src/libgamma_Partition.c +++ b/src/libgamma_Partition.c @@ -18,7 +18,32 @@ #include "libgamma_Partition.h" +/** + * Create a partition state. + * + * @param site The site state for the site that the partition belongs to. + * @param partition The index of the partition within the site. + * @return Element 0: The value for {@link #address}. + * Element 1: The value for {@link #crtcs_available} + * Element 2: Error code, zero on success. + */ jlongArray Java_libgamma_Partition_libgamma_1partition_1create(JNIEnv *, jclass, jlong, jint); + + +/** + * Release all resources held by a partition state + * and free the partition state pointer. + * + * @param address The partition state. + */ void Java_libgamma_Partition_libgamma_1partition_1free(JNIEnv *, jclass, jlong); + + +/** + * Restore the gamma ramps all CRTC:s within a partition to the system settings. + * + * @param address The partition state. + * @return Zero on success, and error code on failure. + */ jint Java_libgamma_Partition_libgamma_1partition_1restore(JNIEnv *, jclass, jlong); diff --git a/src/libgamma_Ramp.c b/src/libgamma_Ramp.c index f81470f..98fa6d8 100644 --- a/src/libgamma_Ramp.c +++ b/src/libgamma_Ramp.c @@ -18,16 +18,123 @@ #include "libgamma_Ramp.h" +/** + * Read the value of a stop in an 8-bit ramp. + * + * @param address The address of the ramp. + * @param stop The index of the stop. + * @return The value of the stop. + */ jshort Java_libgamma_Ramp_libgamma_1gamma_1ramps8_1get(JNIEnv *, jclass, jlong, jint); + + +/** + * Read the value of a stop in a 16-bit ramp. + * + * @param address The address of the ramp. + * @param stop The index of the stop. + * @return The value of the stop. + */ jint Java_libgamma_Ramp_libgamma_1gamma_1ramps16_1get(JNIEnv *, jclass, jlong, jint); + + +/** + * Read the value of a stop in a 32-bit ramp. + * + * @param address The address of the ramp. + * @param stop The index of the stop. + * @return The value of the stop. + */ jlong Java_libgamma_Ramp_libgamma_1gamma_1ramps32_1get(JNIEnv *, jclass, jlong, jint); + + +/** + * Read the value of a stop in a 64-bit ramp. + * + * @param address The address of the ramp. + * @param stop The index of the stop. + * @return The value of the stop. + */ jlong Java_libgamma_Ramp_libgamma_1gamma_1ramps64_1get(JNIEnv *, jclass, jlong, jint); + + +/** + * Read the value of a stop in a single precision floating point ramp. + * + * @param address The address of the ramp. + * @param stop The index of the stop. + * @return The value of the stop. + */ jfloat Java_libgamma_Ramp_libgamma_1gamma_1rampsf_1get(JNIEnv *, jclass, jlong, jint); + + +/** + * Read the value of a stop in a double precision floating point ramp. + * + * @param address The address of the ramp. + * @param stop The index of the stop. + * @return The value of the stop. + */ jdouble Java_libgamma_Ramp_libgamma_1gamma_1rampsd_1get(JNIEnv *, jclass, jlong, jint); + + + +/** + * Set the value of a stop in an 8-bit ramp. + * + * @param address The address of the ramp. + * @param stop The index of the stop. + * @param value The value of the stop. + */ void Java_libgamma_Ramp_libgamma_1gamma_1ramps8_1set(JNIEnv *, jclass, jlong, jint, jshort); + + +/** + * Set the value of a stop in a 16-bit ramp. + * + * @param address The address of the ramp. + * @param stop The index of the stop. + * @param value The value of the stop. + */ void Java_libgamma_Ramp_libgamma_1gamma_1ramps16_1set(JNIEnv *, jclass, jlong, jint, jint); + + +/** + * Set the value of a stop in a 32-bit ramp. + * + * @param address The address of the ramp. + * @param stop The index of the stop. + * @param value The value of the stop. + */ void Java_libgamma_Ramp_libgamma_1gamma_1ramps32_1set(JNIEnv *, jclass, jlong, jint, jlong); + + +/** + * Set the value of a stop in a 64-bit ramp. + * + * @param address The address of the ramp. + * @param stop The index of the stop. + * @param value The value of the stop. + */ void Java_libgamma_Ramp_libgamma_1gamma_1ramps64_1set(JNIEnv *, jclass, jlong, jint, jlong); + + +/** + * Set the value of a stop in a single precision floating point ramp. + * + * @param address The address of the ramp. + * @param stop The index of the stop. + * @param value The value of the stop. + */ void Java_libgamma_Ramp_libgamma_1gamma_1rampsf_1set(JNIEnv *, jclass, jlong, jint, jfloat); + + +/** + * Set the value of a stop in a double precision floating point ramp. + * + * @param address The address of the ramp. + * @param stop The index of the stop. + * @param value The value of the stop. + */ void Java_libgamma_Ramp_libgamma_1gamma_1rampsd_1set(JNIEnv *, jclass, jlong, jint, jdouble); diff --git a/src/libgamma_Site.c b/src/libgamma_Site.c index da7fdd2..ba66c35 100644 --- a/src/libgamma_Site.c +++ b/src/libgamma_Site.c @@ -18,7 +18,32 @@ #include "libgamma_Site.h" +/** + * Create a site state. + * + * @param method The adjustment method (display server and protocol.) + * @param site The site identifier. + * @return Element 0: The value for {@link #address}. + * Element 1: The value for {@link #partitions_available} + * Element 2: Error code, zero on success. + */ jlongArray Java_libgamma_Site_libgamma_1site_1create(JNIEnv *, jclass, jint, jstring); + + +/** + * Release all resources held by a site state + * and free the site state pointer. + * + * @param address The site state. + */ void Java_libgamma_Site_libgamma_1site_1free(JNIEnv *, jclass, jlong); + + +/** + * Restore the gamma ramps all CRTC:s within a site to the system settings. + * + * @param address The site state. + * @return Zero on success, and error code on failure. + */ jint Java_libgamma_Site_libgamma_1site_1restore(JNIEnv *, jclass, jlong); -- cgit v1.2.3-70-g09d2